Performer Operations¶

Operations for managing performers (actors/models).

Bases: StashClientProtocol

Mixin for performer-related client methods.

Functions¶

find_performer `async` ¶

find_performer(
    performer: int | str | dict,
) -> Performer | None

Find a performer by ID, name, or filter.

Parameters:

Name	Type	Description	Default
`performer`	`int \| str \| dict`	Can be: - ID (int/str): Find by ID - Name (str): Find by name - Dict: Find by filter criteria	required

Returns:

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

Examples:

Find by ID:

performer = await client.find_performer("123")
if performer:
    print(f"Found performer: {performer.name}")

Find by name:

performer = await client.find_performer("Performer Name")
if performer:
    print(f"Found performer with ID: {performer.id}")

Find by filter:

performer = await client.find_performer({
    "name": "Performer Name",
    "disambiguation": "2000s"
})

Access performer relationships:

performer = await client.find_performer("123")
if performer:
    # Get scene titles
    scene_titles = [s.title for s in performer.scenes]
    # Get studio name
    studio_name = performer.studio.name if performer.studio else None
    # Get tag names
    tags = [t.name for t in performer.tags]

find_performers `async` ¶

find_performers(
    filter_: dict[str, Any] | None = None,
    performer_filter: dict[str, Any] | None = None,
    q: str | None = None,
) -> FindPerformersResultType

Find performers 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`
`q`	`str \| None`	Optional search query (alternative to filter_["q"])	`None`
`performer_filter`	`dict[str, Any] \| None`	Optional performer-specific filter: - birth_year: IntCriterionInput - age: IntCriterionInput - ethnicity: StringCriterionInput - country: StringCriterionInput - eye_color: StringCriterionInput - height: StringCriterionInput - measurements: StringCriterionInput - fake_tits: StringCriterionInput - career_length: StringCriterionInput - tattoos: StringCriterionInput - piercings: StringCriterionInput - favorite: bool - rating100: IntCriterionInput - gender: GenderEnum - is_missing: str (what data is missing) - name: StringCriterionInput - studios: HierarchicalMultiCriterionInput - tags: HierarchicalMultiCriterionInput	`None`

Returns:

Type	Description
`FindPerformersResultType`	FindPerformersResultType containing: - count: Total number of matching performers - performers: List of Performer objects

Examples:

Find all favorite performers:

result = await client.find_performers(
    performer_filter={"favorite": True}
)
print(f"Found {result.count} favorite performers")
for performer in result.performers:
    print(f"- {performer.name}")

Find performers with specific tags:

result = await client.find_performers(
    performer_filter={
        "tags": {
            "value": ["tag1", "tag2"],
            "modifier": "INCLUDES_ALL"
        }
    }
)

Find performers with high rating and sort by name:

result = await client.find_performers(
    filter_={
        "direction": "ASC",
        "sort": "name",
    },
    performer_filter={
        "rating100": {
            "value": 80,
            "modifier": "GREATER_THAN"
        }
    }
)

Paginate results:

result = await client.find_performers(
    filter_={
        "page": 1,
        "per_page": 25,
    }
)

create_performer `async` ¶

create_performer(performer: Performer) -> Performer

Create a new performer in Stash.

Parameters:

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

Returns:

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

Raises:

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

Examples:

Create a basic performer:

performer = Performer(
    name="Performer Name",
)
created = await client.create_performer(performer)
print(f"Created performer with ID: {created.id}")

Create performer with metadata:

name="__codelineno-1-1" href="#__codelineno-1-1">performer = Performer( name="Performer Name", # Add metadata gender="FEMALE", birthdate="1990-01-01", ethnicity="Caucasian", country="USA", eye_color="Blue", height_cm=170, measurements="34B-24-36", fake_tits="No", career_length="2010-2020", tattoos="None", piercings="Ears", url="https://example.com/performer", twitter="@performer", instagram="@performer", details="Performer details", class="p">) class="n">created = await client.create_performer(performer)

Create performer with relationships:

performer = Performer(
    name="Performer Name",
    # Add relationships
    tags=[tag1, tag2],
    image="https://example.com/image.jpg",
    stash_ids=[stash_id1, stash_id2],
)
created = await client.create_performer(performer)

update_performer `async` ¶

update_performer(performer: Performer) -> Performer

Update an existing performer in Stash.

Parameters:

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

Returns:

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

Raises:

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

Examples:

Update performer name and metadata:

performer = await client.find_performer("123")
if performer:
    performer.name = "New Name"
    performer.gender = "FEMALE"
    performer.birthdate = "1990-01-01"
    updated = await client.update_performer(performer)
    print(f"Updated performer: {updated.name}")

Update performer relationships:

performer = await client.find_performer("123")
if performer:
    # Add new tags
    performer.tags.extend([new_tag1, new_tag2])
    # Update image
    performer.image = "https://example.com/new-image.jpg"
    updated = await client.update_performer(performer)

Update performer URLs:

performer = await client.find_performer("123")
if performer:
    # Replace URLs
    performer.url = "https://example.com/new-url"
    performer.twitter = "@new_twitter"
    performer.instagram = "@new_instagram"
    updated = await client.update_performer(performer)

Remove performer relationships:

performer = await client.find_performer("123")
if performer:
    # Clear tags
    performer.tags = []
    # Clear image
    performer.image = None
    updated = await client.update_performer(performer)

update_performer_image `async` ¶

update_performer_image(
    performer: Performer, image_url: str
) -> Performer

Update a performer's image.

Parameters:

Name	Type	Description	Default
`performer`	`Performer`	Performer object with at least the ID set	required
`image_url`	`str`	URL or data URI of the image to set	required

Returns:

Type	Description
`Performer`	Updated Performer object with the new image

Raises:

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

Examples:

Update performer image with a data URI:

performer = await client.find_performer("123")
if performer:
    # Update with data URI
    image_url = "data:image/jpeg;base64,..."
    updated = await client.update_performer_image(performer, image_url)

Update performer image from a file:

performer = await client.find_performer("123")
if performer:
    # Use the performer's update_avatar method
    updated = await performer.update_avatar(client, "/path/to/image.jpg")

performer_destroy `async` ¶

performer_destroy(
    input_data: PerformerDestroyInput | dict[str, Any],
) -> bool

Delete a performer.

Parameters:

Name	Type	Description	Default
`input_data`	`PerformerDestroyInput \| dict[str, Any]`	PerformerDestroyInput object or dictionary containing: - id: Performer ID to delete (required)	required

Returns:

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

Raises:

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

Examples:

Delete a performer:

result = await client.performer_destroy({"id": "123"})
print(f"Performer deleted: {result}")

Using the input type:

from ...types import PerformerDestroyInput

input_data = PerformerDestroyInput(id="123")
result = await client.performer_destroy(input_data)

performers_destroy `async` ¶

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

Delete multiple performers.

Parameters:

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

Returns:

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

Raises:

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

Examples:

Delete multiple performers:

result = await client.performers_destroy(["123", "456", "789"])
print(f"Performers deleted: {result}")

all_performers `async` ¶

all_performers() -> list[Performer]

Get all performers.

bulk_performer_update `async` ¶

bulk_performer_update(
    input_data: BulkPerformerUpdateInput | dict[str, Any],
) -> list[Performer]

Bulk update performers.

Parameters:

Name	Type	Description	Default
`input_data`	`BulkPerformerUpdateInput \| dict[str, Any]`	BulkPerformerUpdateInput object or dictionary containing: - ids: List of performer IDs to update (optional) - And any fields to update (e.g., gender, birthdate, tags, etc.)	required

Returns:

Type	Description
`list[Performer]`	List of updated Performer objects

Examples:

Update multiple performers' gender:

performers = await client.bulk_performer_update({
    "ids": ["1", "2", "3"],
    "gender": "FEMALE"
})

Add tags to multiple performers:

from stash_graphql_client.types import BulkPerformerUpdateInput, BulkUpdateIds

input_data = BulkPerformerUpdateInput(
    ids=["1", "2", "3"],
    tag_ids=BulkUpdateIds(ids=["tag1", "tag2"], mode="ADD")
)
performers = await client.bulk_performer_update(input_data)

performer_merge `async` ¶

performer_merge(
    input_data: PerformerMergeInput | dict[str, Any],
) -> Performer

Merge performers into a single performer.

Minimum Stash Version: v0.30.2+ or commit 65e82a0 or newer

This feature requires Stash v0.30.2 or later (or development builds with commit 65e82a0+). Older Stash versions will raise a GraphQL error.

Parameters:

Name	Type	Description	Default
`input_data`	`PerformerMergeInput \| dict[str, Any]`	PerformerMergeInput object or dictionary containing: - source: List of performer IDs to merge (required) - destination: ID of the performer to merge into (required) - values: Optional PerformerUpdateInput to override destination values	required

Returns:

Type	Description
`Performer`	The merged Performer object

Raises:

Type	Description
`StashGraphQLError`	If Stash version is too old or merge fails

Examples:

Merge performers:

merged = await client.performer_merge({
    "source": ["performer1-id", "performer2-id"],
    "destination": "destination-performer-id"
})

Merge with overrides:

from stash_graphql_client.types import PerformerMergeInput, PerformerUpdateInput

merged = await client.performer_merge(
    PerformerMergeInput(
        source=["performer1-id", "performer2-id"],
        destination="destination-performer-id",
        values=PerformerUpdateInput(
            id="destination-performer-id",
            name="New Name",
            gender="FEMALE"
        )
    )
)

map_performer_ids `async` ¶

map_performer_ids(
    performers: list[str | dict[str, Any] | Performer],
    create: bool = False,
    on_multiple: OnMultipleMatch = RETURN_FIRST,
) -> list[str]

Convert performer names/objects to IDs, optionally creating missing performers.

This is a convenience method to resolve performer references to their IDs, reducing boilerplate when working with performer relationships.

Parameters:

Name	Type	Description	Default
`performers`	`list[str \| dict[str, Any] \| Performer]`	List of performer references, can be: - str: Performer name (searches by name, then aliases) - dict: Performer filter criteria (e.g., {"name": "John", "disambiguation": "Actor"}) - Performer: Performer object (extracts ID if present, otherwise searches by name)	required
`create`	`bool`	If True, create performers that don't exist. Default is False.	`False`
`on_multiple`	`OnMultipleMatch`	Strategy when multiple matches found. Default is RETURN_FIRST.	`RETURN_FIRST`

Returns:

Type	Description
`list[str]`	List of performer IDs. Skips performers that aren't found (unless create=True).

Examples:

Map performer names to IDs:

performer_ids = await client.map_performer_ids(["Jane Doe", "John Smith"])
# Returns: ["1", "2"] (IDs of existing performers)

Auto-create missing performers:

performer_ids = await client.map_performer_ids(
    ["Jane Doe", "NewPerformer"],
    create=True
)
# Creates "NewPerformer" if it doesn't exist

Handle multiple matches:

performer_ids = await client.map_performer_ids(
    ["AmbiguousName"],
    on_multiple=OnMultipleMatch.RETURN_NONE  # Skip ambiguous matches
)

Use in scene creation:

scene = Scene(
    title="My Scene",
    performers=[]  # Will populate with performer IDs
)
scene.performers = await client.map_performer_ids(
    ["Jane Doe", "John Smith"],
    create=True
)
created_scene = await client.create_scene(scene)

Performer Operations¶

Functions¶

find_performer async ¶

find_performers async ¶

create_performer async ¶

update_performer async ¶

update_performer_image async ¶

performer_destroy async ¶

performers_destroy async ¶

all_performers async ¶

bulk_performer_update async ¶

performer_merge async ¶

map_performer_ids async ¶

find_performer `async` ¶

find_performers `async` ¶

create_performer `async` ¶

update_performer `async` ¶

update_performer_image `async` ¶

performer_destroy `async` ¶

performers_destroy `async` ¶

all_performers `async` ¶

bulk_performer_update `async` ¶

performer_merge `async` ¶

map_performer_ids `async` ¶