Scraper Operations¶

Operations for scraping metadata from external sources.

Bases: StashClientProtocol

Mixin for scraper-related client methods.

Functions¶

list_scrapers `async` ¶

list_scrapers(
    types: list[ScrapeContentType],
) -> list[Scraper]

List available scrapers filtered by content types.

Parameters:

Name	Type	Description	Default
`types`	`list[ScrapeContentType]`	List of content types to filter scrapers by (GALLERY, IMAGE, MOVIE, GROUP, PERFORMER, SCENE)	required

Returns:

Type	Description
`list[Scraper]`	List of Scraper objects matching the requested types

Examples:

List all scene scrapers:

scrapers = await client.list_scrapers([ScrapeContentType.SCENE])
for scraper in scrapers:
    print(f"Scene scraper: {scraper.name}")

List multiple scraper types:

from stash_graphql_client.types import ScrapeContentType
scrapers = await client.list_scrapers([
    ScrapeContentType.SCENE,
    ScrapeContentType.PERFORMER
])

Check scraper capabilities:

scrapers = await client.list_scrapers([ScrapeContentType.SCENE])
for scraper in scrapers:
    if scraper.scene:
        print(f"{scraper.name} supports: {scraper.scene.supported_scrapes}")
        print(f"URLs: {scraper.scene.urls}")

scrape_single_scene `async` ¶

scrape_single_scene(
    source: ScraperSourceInput,
    input: ScrapeSingleSceneInput,
) -> list[ScrapedScene]

Scrape for a single scene.

Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleSceneInput`	Scene scraping input (query, scene_id, or scene_input)	required

Returns:

Type	Description
`list[ScrapedScene]`	List of ScrapedScene objects

Examples:

Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleSceneInput(query="scene title")
scenes = await client.scrape_single_scene(source, input)

Scrape by scene ID (using fingerprints):

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleSceneInput(scene_id="scene-456")
scenes = await client.scrape_single_scene(source, input)

Scrape from StashBox:

source = ScraperSourceInput(stash_box_endpoint="https://stashdb.org")
input = ScrapeSingleSceneInput(query="scene title")
scenes = await client.scrape_single_scene(source, input)

scrape_multi_scenes `async` ¶

scrape_multi_scenes(
    source: ScraperSourceInput,
    input: ScrapeMultiScenesInput,
) -> list[list[ScrapedScene]]

Scrape for multiple scenes.

Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeMultiScenesInput`	Multi-scene scraping input (scene_ids)	required

Returns:

Type	Description
`list[list[ScrapedScene]]`	List of lists of ScrapedScene objects (one list per input scene)

Examples:

Scrape multiple scenes:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeMultiScenesInput(scene_ids=["1", "2", "3"])
results = await client.scrape_multi_scenes(source, input)
for i, scenes in enumerate(results):
    print(f"Scene {i+1}: {len(scenes)} matches found")

scrape_single_studio `async` ¶

scrape_single_studio(
    source: ScraperSourceInput,
    input: ScrapeSingleStudioInput,
) -> list[ScrapedStudio]

Scrape for a single studio.

Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleStudioInput`	Studio scraping input (query - can be name or Stash ID)	required

Returns:

Type	Description
`list[ScrapedStudio]`	List of ScrapedStudio objects

Examples:

Scrape studio by name:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleStudioInput(query="Studio Name")
studios = await client.scrape_single_studio(source, input)

scrape_single_tag `async` ¶

scrape_single_tag(
    source: ScraperSourceInput, input: ScrapeSingleTagInput
) -> list[ScrapedTag]

Scrape for a single tag.

Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleTagInput`	Tag scraping input (query - can be name or Stash ID)	required

Returns:

Type	Description
`list[ScrapedTag]`	List of ScrapedTag objects

Examples:

Scrape tag by name:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleTagInput(query="Tag Name")
tags = await client.scrape_single_tag(source, input)

Scrape from StashBox:

source = ScraperSourceInput(stash_box_endpoint="https://stashdb.org")
input = ScrapeSingleTagInput(query="Tag Name")
tags = await client.scrape_single_tag(source, input)

scrape_single_performer `async` ¶

scrape_single_performer(
    source: ScraperSourceInput,
    input: ScrapeSinglePerformerInput,
) -> list[ScrapedPerformer]

Scrape for a single performer.

Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSinglePerformerInput`	Performer scraping input (query, performer_id, or performer_input)	required

Returns:

Type	Description
`list[ScrapedPerformer]`	List of ScrapedPerformer objects

Examples:

Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSinglePerformerInput(query="Performer Name")
performers = await client.scrape_single_performer(source, input)

Scrape by performer ID:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSinglePerformerInput(performer_id="123")
performers = await client.scrape_single_performer(source, input)

scrape_multi_performers `async` ¶

scrape_multi_performers(
    source: ScraperSourceInput,
    input: ScrapeMultiPerformersInput,
) -> list[list[ScrapedPerformer]]

Scrape for multiple performers.

Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeMultiPerformersInput`	Multi-performer scraping input (performer_ids)	required

Returns:

Type	Description
`list[list[ScrapedPerformer]]`	List of lists of ScrapedPerformer objects (one list per input performer)

Examples:

Scrape multiple performers:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeMultiPerformersInput(performer_ids=["1", "2", "3"])
results = await client.scrape_multi_performers(source, input)
for i, performers in enumerate(results):
    print(f"Performer {i+1}: {len(performers)} matches found")

scrape_single_gallery `async` ¶

scrape_single_gallery(
    source: ScraperSourceInput,
    input: ScrapeSingleGalleryInput,
) -> list[ScrapedGallery]

Scrape for a single gallery.

Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleGalleryInput`	Gallery scraping input (query, gallery_id, or gallery_input)	required

Returns:

Type	Description
`list[ScrapedGallery]`	List of ScrapedGallery objects

Examples:

Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleGalleryInput(query="gallery title")
galleries = await client.scrape_single_gallery(source, input)

Scrape by gallery ID:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleGalleryInput(gallery_id="456")
galleries = await client.scrape_single_gallery(source, input)

scrape_single_movie `async` ¶

scrape_single_movie(
    source: ScraperSourceInput,
    input: ScrapeSingleMovieInput,
) -> list[ScrapedMovie]

Scrape for a single movie.

.. deprecated:: Use :meth:scrape_single_group instead.

Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleMovieInput`	Movie scraping input (query, movie_id, or movie_input)	required

Returns:

Type	Description
`list[ScrapedMovie]`	List of ScrapedMovie objects

Examples:

Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleMovieInput(query="movie title")
movies = await client.scrape_single_movie(source, input)

scrape_single_group `async` ¶

scrape_single_group(
    source: ScraperSourceInput,
    input: ScrapeSingleGroupInput,
) -> list[ScrapedGroup]

Scrape for a single group.

Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleGroupInput`	Group scraping input (query, group_id, or group_input)	required

Returns:

Type	Description
`list[ScrapedGroup]`	List of ScrapedGroup objects

Examples:

Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleGroupInput(query="group title")
groups = await client.scrape_single_group(source, input)

Scrape by group ID:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleGroupInput(group_id="789")
groups = await client.scrape_single_group(source, input)

scrape_single_image `async` ¶

scrape_single_image(
    source: ScraperSourceInput,
    input: ScrapeSingleImageInput,
) -> list[ScrapedImage]

Scrape for a single image.

Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleImageInput`	Image scraping input (query, image_id, or image_input)	required

Returns:

Type	Description
`list[ScrapedImage]`	List of ScrapedImage objects

Examples:

Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleImageInput(query="image title")
images = await client.scrape_single_image(source, input)

Scrape by image ID:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleImageInput(image_id="101")
images = await client.scrape_single_image(source, input)

scrape_url `async` ¶

scrape_url(url: str, ty: ScrapeContentType) -> Any

Scrape content based on a URL.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape	required
`ty`	`ScrapeContentType`	Type of content to scrape (GALLERY, IMAGE, MOVIE, GROUP, PERFORMER, SCENE)	required

Returns:

Type	Description
`Any`	ScrapedContent union type (could be any scraped type based on ty parameter)

Note

Returns ScrapedStudio, ScrapedTag, ScrapedScene, ScrapedGallery, ScrapedImage, ScrapedMovie, ScrapedGroup, or ScrapedPerformer depending on the content type.

Examples:

Scrape a scene from URL:

from stash_graphql_client.types import ScrapeContentType
content = await client.scrape_url(
    "https://example.com/scene/123",
    ScrapeContentType.SCENE
)
if content:
    print(f"Scraped scene: {content.title}")

Scrape a performer from URL:

content = await client.scrape_url(
    "https://example.com/performer/456",
    ScrapeContentType.PERFORMER
)
if content:
    print(f"Scraped performer: {content.name}")

scrape_performer_url `async` ¶

scrape_performer_url(url: str) -> ScrapedPerformer | None

Scrape a complete performer record based on a URL.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape performer from	required

Returns:

Type	Description
`ScrapedPerformer \| None`	ScrapedPerformer object if successful, None otherwise

Examples:

Scrape performer from URL:

performer = await client.scrape_performer_url("https://example.com/performer/123")
if performer:
    print(f"Name: {performer.name}")
    print(f"Birthdate: {performer.birthdate}")
    print(f"Gender: {performer.gender}")

scrape_scene_url `async` ¶

scrape_scene_url(url: str) -> ScrapedScene | None

Scrape a complete scene record based on a URL.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape scene from	required

Returns:

Type	Description
`ScrapedScene \| None`	ScrapedScene object if successful, None otherwise

Examples:

Scrape scene from URL:

scene = await client.scrape_scene_url("https://example.com/scene/123")
if scene:
    print(f"Title: {scene.title}")
    print(f"Date: {scene.date}")
    print(f"Studio: {scene.studio.name if scene.studio else 'Unknown'}")

scrape_gallery_url `async` ¶

scrape_gallery_url(url: str) -> ScrapedGallery | None

Scrape a complete gallery record based on a URL.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape gallery from	required

Returns:

Type	Description
`ScrapedGallery \| None`	ScrapedGallery object if successful, None otherwise

Examples:

Scrape gallery from URL:

gallery = await client.scrape_gallery_url("https://example.com/gallery/123")
if gallery:
    print(f"Title: {gallery.title}")
    print(f"Date: {gallery.date}")
    print(f"Performers: {len(gallery.performers or [])}")

scrape_image_url `async` ¶

scrape_image_url(url: str) -> ScrapedImage | None

Scrape a complete image record based on a URL.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape image from	required

Returns:

Type	Description
`ScrapedImage \| None`	ScrapedImage object if successful, None otherwise

Examples:

Scrape image from URL:

image = await client.scrape_image_url("https://example.com/image/123")
if image:
    print(f"Title: {image.title}")
    print(f"Date: {image.date}")
    print(f"Tags: {len(image.tags or [])}")

scrape_movie_url `async` ¶

scrape_movie_url(url: str) -> ScrapedMovie | None

Scrape a complete movie record based on a URL.

.. deprecated:: Use :meth:scrape_group_url instead.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape movie from	required

Returns:

Type	Description
`ScrapedMovie \| None`	ScrapedMovie object if successful, None otherwise

Examples:

Scrape movie from URL:

movie = await client.scrape_movie_url("https://example.com/movie/123")
if movie:
    print(f"Name: {movie.name}")
    print(f"Date: {movie.date}")
    print(f"Duration: {movie.duration}")

scrape_group_url `async` ¶

scrape_group_url(url: str) -> ScrapedGroup | None

Scrape a complete group record based on a URL.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape group from	required

Returns:

Type	Description
`ScrapedGroup \| None`	ScrapedGroup object if successful, None otherwise

Examples:

Scrape group from URL:

group = await client.scrape_group_url("https://example.com/group/123")
if group:
    print(f"Name: {group.name}")
    print(f"Date: {group.date}")
    print(f"Synopsis: {group.synopsis}")

reload_scrapers `async` ¶

reload_scrapers() -> bool

Reload all scrapers from configuration.

Returns:

Type	Description
`bool`	True if successful, False otherwise

Examples:

Reload scrapers after configuration change:

success = await client.reload_scrapers()
if success:
    print("Scrapers reloaded successfully")
    # List scrapers to verify
    scrapers = await client.list_scrapers([ScrapeContentType.SCENE])
    print(f"Found {len(scrapers)} scene scrapers")

submit_stashbox_fingerprints `async` ¶

submit_stashbox_fingerprints(
    input_data: StashBoxFingerprintSubmissionInput
    | dict[str, Any],
) -> bool

Submit fingerprints to StashBox.

Parameters:

Name	Type	Description	Default
`input_data`	`StashBoxFingerprintSubmissionInput \| dict[str, Any]`	StashBoxFingerprintSubmissionInput object or dictionary	required

Returns:

Type	Description
`bool`	True if successful

submit_stashbox_scene_draft `async` ¶

submit_stashbox_scene_draft(
    input_data: StashBoxDraftSubmissionInput
    | dict[str, Any],
) -> str

Submit scene draft to StashBox.

Parameters:

Name	Type	Description	Default
`input_data`	`StashBoxDraftSubmissionInput \| dict[str, Any]`	StashBoxDraftSubmissionInput object or dictionary	required

Returns:

Type	Description
`str`	Draft ID

submit_stashbox_performer_draft `async` ¶

submit_stashbox_performer_draft(
    input_data: StashBoxDraftSubmissionInput
    | dict[str, Any],
) -> str

Submit performer draft to StashBox.

Parameters:

Name	Type	Description	Default
`input_data`	`StashBoxDraftSubmissionInput \| dict[str, Any]`	StashBoxDraftSubmissionInput object or dictionary	required

Returns:

Type	Description
`str`	Draft ID

stashbox_batch_performer_tag `async` ¶

stashbox_batch_performer_tag(
    input_data: dict[str, Any],
) -> str

Batch tag performers from StashBox.

Parameters:

Name	Type	Description	Default
`input_data`	`dict[str, Any]`	Batch performer tag input dictionary	required

Returns:

Type	Description
`str`	Job ID

stashbox_batch_studio_tag `async` ¶

stashbox_batch_studio_tag(
    input_data: dict[str, Any],
) -> str

Batch tag studios from StashBox.

Parameters:

Name	Type	Description	Default
`input_data`	`dict[str, Any]`	Batch studio tag input dictionary	required

Returns:

Type	Description
`str`	Job ID

stashbox_batch_tag_tag `async` ¶

stashbox_batch_tag_tag(input_data: dict[str, Any]) -> str

Batch tag tags from StashBox.

Parameters:

Name	Type	Description	Default
`input_data`	`dict[str, Any]`	Batch tag input dictionary (StashBoxBatchTagInput)	required

Returns:

Type	Description
`str`	Job ID

Scraper Operations¶

Functions¶

list_scrapers async ¶

scrape_single_scene async ¶

scrape_multi_scenes async ¶

scrape_single_studio async ¶

scrape_single_tag async ¶

scrape_single_performer async ¶

scrape_multi_performers async ¶

scrape_single_gallery async ¶

scrape_single_movie async ¶

scrape_single_group async ¶

scrape_single_image async ¶

scrape_url async ¶

scrape_performer_url async ¶

scrape_scene_url async ¶

scrape_gallery_url async ¶

scrape_image_url async ¶

scrape_movie_url async ¶

scrape_group_url async ¶

reload_scrapers async ¶

submit_stashbox_fingerprints async ¶

submit_stashbox_scene_draft async ¶

submit_stashbox_performer_draft async ¶

stashbox_batch_performer_tag async ¶

stashbox_batch_studio_tag async ¶

stashbox_batch_tag_tag async ¶

list_scrapers `async` ¶

scrape_single_scene `async` ¶

scrape_multi_scenes `async` ¶

scrape_single_studio `async` ¶

scrape_single_tag `async` ¶

scrape_single_performer `async` ¶

scrape_multi_performers `async` ¶

scrape_single_gallery `async` ¶

scrape_single_movie `async` ¶

scrape_single_group `async` ¶

scrape_single_image `async` ¶

scrape_url `async` ¶

scrape_performer_url `async` ¶

scrape_scene_url `async` ¶

scrape_gallery_url `async` ¶

scrape_image_url `async` ¶

scrape_movie_url `async` ¶

scrape_group_url `async` ¶

reload_scrapers `async` ¶

submit_stashbox_fingerprints `async` ¶

submit_stashbox_scene_draft `async` ¶

submit_stashbox_performer_draft `async` ¶

stashbox_batch_performer_tag `async` ¶

stashbox_batch_studio_tag `async` ¶

stashbox_batch_tag_tag `async` ¶