Studio Operations - Stash Tools & Scrapers

Operations for managing studios (production companies). Bases: StashClientProtocol Mixin for studio-related client methods.

Functions

find_studio

find_studio(id: str) -> Studio | None

Find a studio by its ID. Parameters:

Name	Type	Description	Default
`id`	`str`	The ID of the studio to find	required

Returns:

Type	Description
`Studio \| None`	Studio object if found, None otherwise

find_studios

find_studios(
    filter_: dict[str, Any] | None = None,
    studio_filter: dict[str, Any] | None = None,
    q: str | None = None,
) -> FindStudiosResultType

Find studios matching the given filters. Parameters:

Name	Type	Description	Default
`filter_`	`dict[str, Any] \| None`	Optional general filter parameters: - q: str (search query) - direction: SortDirectionEnum (ASC/DESC) - page: int - per_page: int - sort: str (field to sort by)	`None`
`studio_filter`	`dict[str, Any] \| None`	Optional studio-specific filter	`None`
`q`	`str \| None`	Optional search query (alternative to filter_[“q”])	`None`

Returns:

Type	Description
`FindStudiosResultType`	FindStudiosResultType containing: - count: Total number of matching studios - studios: List of Studio objects

create_studio

create_studio(studio: Studio) -> Studio

Create a new studio in Stash. Parameters:

Name	Type	Description	Default
`studio`	`Studio`	Studio object with the data to create. Required fields: - name: Studio name	required

Returns:

Type	Description
`Studio`	Created Studio object with ID and any server-generated fields

Raises:

Type	Description
`ValueError`	If the studio data is invalid
`TransportError`	If the request fails

update_studio

update_studio(studio: Studio) -> Studio

Update an existing studio in Stash. Parameters:

Name	Type	Description	Default
`studio`	`Studio`	Studio object with updated data. Required fields: - id: Studio ID to update Any other fields that are set will be updated. Fields that are None will be ignored.	required

Returns:

Type	Description
`Studio`	Updated Studio object with any server-generated fields

Raises:

Type	Description
`ValueError`	If the studio data is invalid
`TransportError`	If the request fails

studio_destroy

studio_destroy(
    input_data: StudioDestroyInput | dict[str, Any],
) -> bool

Delete a studio. Parameters:

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

Returns:

Type	Description
`bool`	True if the studio was successfully deleted

Raises:

Type	Description
`ValueError`	If the studio ID is invalid
`TransportError`	If the request fails

studios_destroy

studios_destroy(ids: list[str]) -> bool

Delete multiple studios. Parameters:

Name	Type	Description	Default
`ids`	`list[str]`	List of studio IDs to delete	required

Returns:

Type	Description
`bool`	True if the studios were successfully deleted

Raises:

Type	Description
`ValueError`	If any studio ID is invalid
`TransportError`	If the request fails

bulk_studio_update

bulk_studio_update(
    input_data: BulkStudioUpdateInput | dict[str, Any],
) -> list[Studio]

bulk_studio_update(
    input_data: BulkStudioUpdateInput | dict[str, Any],
    *,
    return_fields: str,
) -> list[dict[str, Any]]

bulk_studio_update(
    input_data: BulkStudioUpdateInput | dict[str, Any],
    *,
    return_fields: str | None = None,
) -> list[Studio] | list[dict[str, Any]]

Bulk update studios. Parameters:

Name	Type	Description	Default
`input_data`	`BulkStudioUpdateInput \| dict[str, Any]`	BulkStudioUpdateInput object or dictionary with fields to update.	required
`return_fields`	`str \| None`	If provided, use a minimal inline mutation requesting only these fields (e.g. `"id"`). Returns raw dicts instead of Studio objects.	`None`

Returns:

Type	Description
`list[Studio] \| list[dict[str, Any]]`	List of updated Studio objects (default), or list of dicts when
`list[Studio] \| list[dict[str, Any]]`	`return_fields` is provided.

find_studio_hierarchy

find_studio_hierarchy(studio_id: str) -> list[Studio]

Get full parent chain from root to this studio. Recursively traverses the parent_studio relationship to build a complete hierarchy from the root studio down to the specified studio. Parameters:

Name	Type	Description	Default
`studio_id`	`str`	The ID of the studio to get hierarchy for	required

Returns:

Type	Description
`list[Studio]`	List of Studio objects ordered from root (index 0) to the specified
`list[Studio]`	studio (last index). Returns empty list if studio not found.

Examples: Get studio hierarchy:

# Studio structure: Root > Parent > Child
hierarchy = await client.find_studio_hierarchy("child_id")
# Returns: [<Root Studio>, <Parent Studio>, <Child Studio>]
for i, studio in enumerate(hierarchy):
    print(f"Level {i}: {studio.name}")

Check if studio has parents:

hierarchy = await client.find_studio_hierarchy("studio_id")
if len(hierarchy) > 1:
    print(f"Root studio: {hierarchy[0].name}")
    print(f"Direct parent: {hierarchy[-2].name}")

find_studio_root

find_studio_root(studio_id: str) -> Studio | None

Find the top-level parent studio. Traverses the parent chain to find the root studio (the one with no parent). Parameters:

Name	Type	Description	Default
`studio_id`	`str`	The ID of the studio to find root for	required

Returns:

Type	Description
`Studio \| None`	Root Studio object, or None if studio not found

Examples: Get root studio:

root = await client.find_studio_root("child_studio_id")
if root:
    print(f"Root studio: {root.name}")

Compare studio with its root:

studio = await client.find_studio("studio_id")
root = await client.find_studio_root("studio_id")
if studio and root:
    if studio.id == root.id:
        print("This is a root studio")
    else:
        print(f"Root is: {root.name}")

map_studio_ids

map_studio_ids(
    studios: list[str | dict[str, Any] | Studio],
    create: bool = False,
) -> list[str]

Convert studio names/objects to IDs, optionally creating missing studios. This is a convenience method to resolve studio references to their IDs, reducing boilerplate when working with studio relationships. Parameters:

Name	Type	Description	Default
`studios`	`list[str \| dict[str, Any] \| Studio]`	List of studio references, can be: - str: Studio name (searches for exact match) - dict: Studio filter criteria (e.g., {“name”: “Acme Studios”}) - Studio: Studio object (extracts ID if present, otherwise searches by name)	required
`create`	`bool`	If True, create studios that don’t exist. Default is False.	`False`

Returns:

Type	Description
`list[str]`	List of studio IDs. Skips studios that aren’t found (unless create=True).

Examples: Map studio names to IDs:

studio_ids = await client.map_studio_ids(["Acme", "Foo Studios", "Bar Inc"])
# Returns: ["1", "2", "3"] (IDs of existing studios)

Auto-create missing studios:

studio_ids = await client.map_studio_ids(
    ["Acme", "NewStudio"],
    create=True
)
# Creates "NewStudio" if it doesn't exist

Mix of strings and Studio objects:

studio_obj = Studio(name="Acme")
studio_ids = await client.map_studio_ids([studio_obj, "Foo Studios"])

Use in scene creation:

scene = Scene(
    title="My Scene",
    studio=None  # Will populate with studio ID
)
studio_ids = await client.map_studio_ids(["Acme"], create=True)
if studio_ids:
    scene.studio = Studio(id=studio_ids[0])
created_scene = await client.create_scene(scene)

​Functions

​find_studio

​find_studios

​create_studio

​update_studio

​studio_destroy

​studios_destroy

​bulk_studio_update

​find_studio_hierarchy

​find_studio_root

​map_studio_ids

Functions

find_studio

find_studios

create_studio

update_studio

studio_destroy

studios_destroy

bulk_studio_update

find_studio_hierarchy

find_studio_root

map_studio_ids