Tag Operations

Operations for managing tags (categories/labels).

Bases: StashClientProtocol

Mixin for tag-related client methods.

Functions

find_tag async

find_tag(id: str) -> Tag | None

Find a tag by its ID.

Parameters:

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

Returns:

Type	Description
Tag | None	Tag object if found, None otherwise

find_tags async

find_tags(
    filter_: dict[str, Any] | None = None,
    tag_filter: dict[str, Any] | None = None,
    q: str | None = None,
) -> FindTagsResultType

Find tags 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
tag_filter	dict[str, Any] | None	Optional tag-specific filter	None
q	str | None	Optional search query (alternative to filter_["q"])	None

Returns:

Type	Description
FindTagsResultType	FindTagsResultType containing: - count: Total number of matching tags - tags: List of Tag objects

Note:

create_tag async

create_tag(tag: Tag) -> Tag

Create a new tag in Stash.

Parameters:

Name	Type	Description	Default
tag	Tag	Tag object with the data to create. Required fields: - name: Tag name	required

Returns:

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

Raises:

Type	Description
ValueError	If the tag data is invalid
TransportError	If the request fails

tags_merge async

tags_merge(source: list[str], destination: str) -> Tag

Merge multiple tags into one.

Parameters:

Name	Type	Description	Default
source	list[str]	List of source tag IDs to merge	required
destination	str	Destination tag ID	required

Returns:

Type	Description
Tag	Updated destination Tag object

Raises:

Type	Description
ValueError	If the tag data is invalid
TransportError	If the request fails

bulk_tag_update async

bulk_tag_update(
    ids: list[str],
    description: str | None = None,
    aliases: list[str] | None = None,
    favorite: bool | None = None,
    parent_ids: list[str] | None = None,
    child_ids: list[str] | None = None,
) -> list[Tag]

Update multiple tags at once.

Parameters:

Name	Type	Description	Default
ids	list[str]	List of tag IDs to update	required
description	str | None	Optional description to set	None
aliases	list[str] | None	Optional list of aliases to set	None
favorite	bool | None	Optional favorite flag to set	None
parent_ids	list[str] | None	Optional list of parent tag IDs to set	None
child_ids	list[str] | None	Optional list of child tag IDs to set	None

Returns:

Type	Description
list[Tag]	List of updated Tag objects

Raises:

Type	Description
ValueError	If the tag data is invalid
TransportError	If the request fails

update_tag async

update_tag(tag: Tag) -> Tag

Update an existing tag in Stash.

Parameters:

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

Returns:

Type	Description
Tag	Updated Tag object with any server-generated fields

Raises:

Type	Description
ValueError	If the tag data is invalid
TransportError	If the request fails

tag_destroy async

tag_destroy(
    input_data: TagDestroyInput | dict[str, Any],
) -> bool

Delete a tag.

Parameters:

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

Returns:

Type	Description
bool	True if the tag was successfully deleted

Raises:

Type	Description
ValueError	If the tag ID is invalid
TransportError	If the request fails

tags_destroy async

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

Delete multiple tags.

Parameters:

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

Returns:

Type	Description
bool	True if the tags were successfully deleted

Raises:

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

map_tag_ids async

map_tag_ids(
    tags: list[str | dict[str, Any] | Tag],
    create: bool = False,
) -> list[str]

Convert tag names/objects to IDs, optionally creating missing tags.

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

Parameters:

Name	Type	Description	Default
tags	list[str | dict[str, Any] | Tag]	List of tag references, can be: - str: Tag name (searches for exact match) - dict: Tag filter criteria (e.g., {"name": "Action"}) - Tag: Tag object (extracts ID if present, otherwise searches by name)	required
create	bool	If True, create tags that don't exist. Default is False.	False

Returns:

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

Examples:

Map tag names to IDs:

tag_ids = await client.map_tag_ids(["Action", "Drama", "Comedy"])
# Returns: ["1", "2", "3"] (IDs of existing tags)

Auto-create missing tags:

tag_ids = await client.map_tag_ids(
    ["Action", "NewTag", "Drama"],
    create=True
)
# Creates "NewTag" if it doesn't exist

Mix of strings and Tag objects:

tag_obj = Tag(name="Action")
tag_ids = await client.map_tag_ids([tag_obj, "Drama"])

Use in scene creation:

scene = Scene(
    title="My Scene",
    tags=[]  # Will populate with tag IDs
)
scene.tags = await client.map_tag_ids(
    ["Action", "Drama"],
    create=True
)
created_scene = await client.create_scene(scene)