> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jakan.co/llms.txt
> Use this file to discover all available pages before exploring further.

# File Operations

> Operations for managing files and folders.

Operations for managing files and folders.

Bases: `StashClientProtocol`

Mixin for file-related client methods.

## Functions

### find\_file

```python theme={null}
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:

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

Find a file by path:

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

Check file type:

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
result = await client.find_files(ids=["1", "2", "3"])
```

### move\_files

```python theme={null}
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:

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

Move files to a new folder by ID:

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

Move and rename a single file:

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

### file\_set\_fingerprints

```python theme={null}
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:

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

Set multiple fingerprints:

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

### scene\_assign\_file

```python theme={null}
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:

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

Using the input type:

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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 |