File Operations - Stash Tools & Scrapers

Operations for managing files and folders. Bases: StashClientProtocol Mixin for file-related client methods.

Functions

find_file

find_file(
    id: str | None = None, path: str | None = None
) -> BaseFile | None

Find a file by its ID or path. Parameters:

Name	Type	Description	Default
`id`	`str \| None`	The ID of the file to find (optional)	`None`
`path`	`str \| None`	The path of the file to find (optional)	`None`

Returns:

Type	Description
`BaseFile \| None`	BaseFile object (VideoFile, ImageFile, GalleryFile, or BasicFile) if found,
`BaseFile \| None`	None otherwise

Raises:

Type	Description
`ValueError`	If neither id nor path is provided

Examples: Find a file by ID:

file = await client.find_file(id="123")
if file:
    print(f"Found file: {file.path}")

Find a file by path:

file = await client.find_file(path="/path/to/video.mp4")
if file:
    print(f"File size: {file.size} bytes")

Check file type:

from stash_graphql_client.types import VideoFile, ImageFile

file = await client.find_file(path="/path/to/file.mp4")
if isinstance(file, VideoFile):
    print(f"Video: {file.width}x{file.height}, {file.duration}s")
elif isinstance(file, ImageFile):
    print(f"Image: {file.width}x{file.height}")

find_files

find_files(
    file_filter: dict[str, Any] | None = None,
    filter_: dict[str, Any] | None = None,
    ids: list[str] | None = None,
) -> FindFilesResultType

Find files matching the given filters. Parameters:

Name	Type	Description	Default
`file_filter`	`dict[str, Any] \| None`	Optional file-specific filter: - path: StringCriterionInput - basename: StringCriterionInput - dir: StringCriterionInput - parent_folder: HierarchicalMultiCriterionInput - zip_file: MultiCriterionInput - mod_time: TimestampCriterionInput - size: IntCriterionInput	`None`
`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`
`ids`	`list[str] \| None`	Optional list of file IDs to retrieve	`None`

Returns:

Type	Description
`FindFilesResultType`	FindFilesResultType containing: - count: Total number of matching files - megapixels: Total megapixels of image files - duration: Total duration in seconds of video files - size: Total size in bytes - files: List of BaseFile objects

Examples: Find all files in a directory:

result = await client.find_files(
    file_filter={
        "path": {
            "value": "/videos/",
            "modifier": "INCLUDES"
        }
    }
)
print(f"Found {result.count} files, total size: {result.size} bytes")

Find video files by size:

result = await client.find_files(
    file_filter={
        "size": {
            "value": 1000000000,  # 1GB
            "modifier": "GREATER_THAN"
        }
    }
)
for file in result.files:
    print(f"{file.path}: {file.size} bytes")

Find files by IDs:

result = await client.find_files(ids=["1", "2", "3"])

move_files

move_files(
    input_data: MoveFilesInput | dict[str, Any],
) -> bool

Move files to a new location. Parameters:

Name	Type	Description	Default
`input_data`	`MoveFilesInput \| dict[str, Any]`	MoveFilesInput object or dictionary. Either destination_folder or destination_folder_id must be provided.	required

Returns:

Type	Description
`bool`	True if the move was successful, False otherwise

Examples: Move files to a new folder by path:

success = await client.move_files({
    "ids": ["1", "2", "3"],
    "destination_folder": "/new/location"
})

Move files to a new folder by ID:

success = await client.move_files({
    "ids": ["1", "2"],
    "destination_folder_id": "folder123"
})

Move and rename a single file:

success = await client.move_files({
    "ids": ["1"],
    "destination_folder": "/new/location",
    "destination_basename": "newname.mp4"
})

file_set_fingerprints

file_set_fingerprints(
    input_data: FileSetFingerprintsInput | dict[str, Any],
) -> bool

Set fingerprints for a file. Parameters:

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

Returns:

Type	Description
`bool`	True if the operation was successful, False otherwise

Examples: Set MD5 fingerprint:

success = await client.file_set_fingerprints({
    "id": "file123",
    "fingerprints": [
        {"type": "MD5", "value": "abc123def456"}
    ]
})

Set multiple fingerprints:

success = await client.file_set_fingerprints({
    "id": "file123",
    "fingerprints": [
        {"type": "MD5", "value": "abc123"},
        {"type": "PHASH", "value": "def456"},
    ]
})

scene_assign_file

scene_assign_file(
    input_data: AssignSceneFileInput | dict[str, Any],
) -> bool

Assign a file to a scene. Parameters:

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

Returns:

Type	Description
`bool`	True if the assignment was successful, False otherwise

Examples: Assign a file to a scene:

success = await client.scene_assign_file({
    "scene_id": "scene123",
    "file_id": "file456"
})

Using the input type:

from stash_graphql_client.types import AssignSceneFileInput

input_data = AssignSceneFileInput(
    scene_id="scene123",
    file_id="file456"
)
success = await client.scene_assign_file(input_data)

delete_files

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

Delete files. Parameters:

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

Returns:

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

Raises:

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

destroy_files

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

Destroy file database entries without deleting files from disk. Unlike delete_files, this only removes the DB entry. The file remains on disk and will be re-scanned if the path is still monitored. Parameters:

Name	Type	Description	Default
`ids`	`list[str]`	List of file IDs to destroy	required

Returns:

Type	Description
`bool`	True if the operation was successful

Raises:

Type	Description
`TransportError`	If the request fails

reveal_file_in_file_manager

reveal_file_in_file_manager(id: str) -> bool

Open the file’s containing folder in the OS file manager. Parameters:

Name	Type	Description	Default
`id`	`str`	File ID to reveal	required

Returns:

Type	Description
`bool`	True if the operation was accepted by the server

Raises:

Type	Description
`TransportError`	If the request fails

reveal_folder_in_file_manager

reveal_folder_in_file_manager(id: str) -> bool

Open the folder in the OS file manager. Parameters:

Name	Type	Description	Default
`id`	`str`	Folder ID to reveal	required

Returns:

Type	Description
`bool`	True if the operation was accepted by the server

Raises:

Type	Description
`TransportError`	If the request fails

find_folder

find_folder(
    id: str | None = None, path: str | None = None
) -> Folder | None

Find a folder by its ID or path. Parameters:

Name	Type	Description	Default
`id`	`str \| None`	The ID of the folder to find (optional)	`None`
`path`	`str \| None`	The path of the folder to find (optional)	`None`

Returns:

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

Raises:

Type	Description
`ValueError`	If neither id nor path is provided

find_folders

find_folders(
    folder_filter: FolderFilterType
    | dict[str, Any]
    | None = None,
    filter_: dict[str, Any] | None = None,
    ids: list[str] | None = None,
) -> FindFoldersResultType

Find folders matching the given filters. Parameters:

Name	Type	Description	Default
`folder_filter`	`FolderFilterType \| dict[str, Any] \| None`	Optional folder-specific filter (FolderFilterType or dict)	`None`
`filter_`	`dict[str, Any] \| None`	Optional general filter parameters (FindFilterType or dict)	`None`
`ids`	`list[str] \| None`	Optional list of folder IDs to retrieve	`None`

Returns:

Type	Description
`FindFoldersResultType`	FindFoldersResultType containing count and list of folders

​Functions

​find_file

​find_files

​move_files

​file_set_fingerprints

​scene_assign_file

​delete_files

​destroy_files

​reveal_file_in_file_manager

​reveal_folder_in_file_manager

​find_folder

​find_folders

Functions

find_file

find_files

move_files

file_set_fingerprints

scene_assign_file

delete_files

destroy_files

reveal_file_in_file_manager

reveal_folder_in_file_manager

find_folder

find_folders