# filesystem

Python API: `luxonis_ml.utils.filesystem`

## Classes

| Name | Description |
| --- | --- |
|
[`FSType`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md)
| Filesystem backend type. |
|
[`LuxonisFileSystem`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md)
| An abstraction over remote and local sources. |
|
[`PutFile`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md)
| Protocol for the `put_file` plugins. |

### class `FSType`

```python
class FSType(Enum)
```

Filesystem backend type.

Attributes

| Name | Type | Description |
| --- | --- | --- |
| `FSSPEC` | `str` | fsspec-compatible filesystem. |
| `MLFLOW` | `str` | MLflow artifact storage. |

### class `LuxonisFileSystem`

```python
class LuxonisFileSystem
```

An abstraction over remote and local sources.

This class provides a unified interface for file operations across different storage backends, including local filesystems, S3,
GCS, and MLflow artifact storage. The backend is chosen by the protocol of the URL:

```pycon
file://<path>
s3://<bucket>/<path>
gcs://<bucket>/<path>
mlflow://<experiment_id>/<run_id>/<artifact_path>
```

A path with no protocol is treated as a local one. For MLflow the `<artifact_path>` is optional and defaults to the run's artifact
root, so `mlflow://<experiment_id>/<run_id>` is itself a valid destination. A bare `mlflow://` binds the filesystem to whichever
run is currently active instead, and requires `allow_active_mlflow_run=True`. MLflow artifacts cannot be removed, so the
`delete_*` methods raise `NotImplementedError` for them.

For more flexibility, users can register custom implementations of the `put_file` method in `PUT_FILE_REGISTRY`. Its name can then
be passed as the `put_file_plugin` argument when initializing `LuxonisFileSystem`. This allows for custom upload logic, such as
additional processing before upload or integration with other services.

> **Example**
> ```pycon
>>> @PUT_FILE_REGISTRY.register()
... def put_file_plugin(*args, **kwargs) -> str:
...     print("Custom put_file called!")
...     return "remote_path"
>>> fs = LuxonisFileSystem(
...     "file:///tmp/luxonis-ml",
...     put_file_plugin="put_file_plugin",
... )
>>> remote_path = fs.put_file("local/file.txt", "remote/file.txt")
Custom put_file called!
>>> print(remote_path)
remote_path
```

Uploading to the artifact store of a specific MLflow run, which returns the URL of the new artifact.

```pycon
fs = LuxonisFileSystem(
    "mlflow://12/abc123/checkpoints",
    tracking_uri="http://localhost:5000",
)
fs.put_file("model.ckpt", "best.ckpt")
# -> "mlflow://12/abc123/checkpoints/best.ckpt"
```

Properties

| Name | Type | Description |
| --- | --- | --- |
| [`artifact_path`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | `str | None` | MLflow artifact path. |
| [`experiment_id`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | `str | None` | MLflow experiment ID. |
| [`full_path`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | `str` | Full remote path. |
| [`is_fsspec`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | `bool` | Check whether the filesystem uses fsspec. |
| [`is_mlflow`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | `bool` | Check whether the filesystem is an MLflow filesystem. |
| [`protocol`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | `str` | Returns the protocol of the filesystem. |
| [`run_id`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | `str | None` | MLflow run ID. |
| [`tracking_uri`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | `str | None` | MLflow tracking URI. |

Methods

| Name | Description |
| --- | --- |
| [`__init__`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Initialize the `LuxonisFileSystem`. |
| [`delete_dir`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Delete a directory and all its contents from remote storage. |
| [`delete_file`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Delete a single file from remote storage. |
| [`delete_files`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Delete multiple files from remote storage. |
| [`download`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Download file or directory from remote storage. |
| [`exists`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Check whether the given remote path exists. |
| [`get_dir`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Copy many files from remote storage to local storage. |
| [`get_file`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Copy a single file from remote storage. |
| [`get_file_uuid`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Read a file and returns the (unique) UUID generated from file bytes. |
| [`get_file_uuids`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Compute the UUIDs for all files stored in the filesystem. |
| [`get_protocol`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Extract the detected protocol from a path. |
| [`init_fsspec_filesystem`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Initialize an `fsspec` filesystem for the configured protocol. |
| [`is_directory`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Check whether the given remote path is a directory. |
| [`put_bytes`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Upload a file to remote storage directly from file bytes. |
| [`put_dir`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Upload files to remote storage. |
| [`put_file`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Copy a single file to remote storage. |
| [`read_text`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Read a file into a string. |
| [`read_to_byte_buffer`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Read a file into a byte buffer. |
| [`split_full_path`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Split the full path into protocol and absolute path. |
| [`upload`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Upload file or directory to remote storage. |
| [`walk_dir`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | Walk through the individual files in a remote directory. |

#### property `artifact_path`

```python
artifact_path: str | None
```

MLflow artifact path.

Returns

| Type | Description |
| --- | --- |
|  | The artifact path relative to the run's artifact root, or `None` if the filesystem is not an MLflow filesystem or no artifact path was given. |

#### property `experiment_id`

```python
experiment_id: str | None
```

MLflow experiment ID.

Returns

| Type | Description |
| --- | --- |
|  | The experiment ID, or `None` if the filesystem is not an MLflow filesystem or the experiment is not known. |

#### property `full_path`

```python
full_path: str
```

Full remote path.

Returns

| Type | Description |
| --- | --- |
|  | Full remote path prefixed with the protocol. |

#### property `is_fsspec`

```python
is_fsspec: bool
```

Check whether the filesystem uses fsspec.

Returns

| Type | Description |
| --- | --- |
|  | `True` if the filesystem uses fsspec. |

#### property `is_mlflow`

```python
is_mlflow: bool
```

Check whether the filesystem is an MLflow filesystem.

Returns

| Type | Description |
| --- | --- |
|  | `True` if the filesystem is an MLflow filesystem, |

#### property `protocol`

```python
protocol: str
```

Returns the protocol of the filesystem.

@type: str

#### property `run_id`

```python
run_id: str | None
```

MLflow run ID.

Returns

| Type | Description |
| --- | --- |
|  | The run ID, or `None` if the filesystem is not an MLflow filesystem or the run is not known. |

#### property `tracking_uri`

```python
tracking_uri: str | None
```

MLflow tracking URI.

Returns

| Type | Description |
| --- | --- |
|  | The tracking URI, or `None` if the filesystem is not an MLflow filesystem. |

#### method `__init__`

```python
def __init__(
    path: str,
    allow_active_mlflow_run: bool | None = False,
    allow_local: bool | None = True,
    cache_storage: str | None = None,
    put_file_plugin: str | None = None,
    tracking_uri: str | None = None,
)
```

Initialize the `LuxonisFileSystem`.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `path` | `str` | Input path consisting of a protocol and path, or only a path for local files. MLflow paths are of the form `mlflow://<experiment_id>/<run_id>/<artifact_path>`, where the artifact path is optional, or a bare `mlflow://` to use the active run. | required |
| `allow_active_mlflow_run` | `bool | None` | Whether operations are allowed on the active MLflow run. | `False` |
| `allow_local` | `bool | None` | Whether operations are allowed on the local file system. | `True` |
| `cache_storage` | `str | None` | Path to an `fsspec` `filecache` directory, used only by the `s3://` and `gcs://` backends. No cache is used if not set, and it is ignored, with a warning, for `file://` and `mlflow://`. | `None` |
| `put_file_plugin` | `str | None` | Name of a registered function in [PUT_FILE_REGISTRY](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) to use instead of [LuxonisFileSystem.put_file](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md). The registered function must conform to the [PutFile](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) protocol. | `None` |
| `tracking_uri` | `str | None` | MLflow tracking URI to use. If omitted, `MLFLOW_TRACKING_URI` from the environment is used. | `None` |

Raises

 * `ValueError`: 1. If the protocol is not supported.
    2. If the protocol is `"file"` but local files are not allowed.
    * `If the protocol is`"mlflow"`but no MLflow path is`: specified and using the active MLflow run is not allowed.
    * `If the protocol is`"mlflow"`but there`: is no `"MLFLOW_TRACKING_URI"` in environment variables.

#### method `delete_dir`

```python
def delete_dir(remote_dir: PosixPathType = '', allow_delete_parent: bool = False)
```

Delete a directory and all its contents from remote storage.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `remote_dir` | `PosixPathType` | Relative path to the remote directory. | `''` |
| `allow_delete_parent` | `bool` | Whether to allow deleting the parent directory. | `False` |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | If no directory is specified and deleting the parent directory is not allowed. |
| `NotImplementedError` | If using MLflow, whose artifacts cannot be deleted. |

#### method `delete_file`

```python
def delete_file(remote_path: PosixPathType)
```

Delete a single file from remote storage.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `remote_path` | `PosixPathType` | Relative path to the remote file. | required |

Raises

| Type | Description |
| --- | --- |
| `NotImplementedError` | If using MLflow, whose artifacts cannot be deleted. |

#### method `delete_files`

```python
def delete_files(remote_paths: list[PosixPathType])
```

Delete multiple files from remote storage.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `remote_paths` | `list[PosixPathType]` | Relative paths to remote files. | required |

Raises

| Type | Description |
| --- | --- |
| `NotImplementedError` | If using MLflow, whose artifacts cannot be deleted. |

#### static method `download`

```python
def download(url: str, dest: PathType | None, tracking_uri: str | None = None) -> Path
```

Download file or directory from remote storage.

Intended for downloading a single remote object without needing to create a `LuxonisFileSystem` instance.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `url` | `str` | URL to the file or directory. | required |
| `dest` | `PathType | None` | Destination directory. If `None`, the current working directory is used. | required |
| `tracking_uri` | `str | None` | MLflow tracking URI to use for `mlflow://` URLs. | `None` |

Returns

| Type | Description |
| --- | --- |
| `Path` | Path to the downloaded file or directory. When the destination already exists, the data is nested inside it and the nested path is returned. |

#### method `exists`

```python
def exists(remote_path: PosixPathType = '') -> bool
```

Check whether the given remote path exists.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `remote_path` | `PosixPathType` | Relative path to the remote file. Defaults to an empty string, which represents the root path of the filesystem. | `''` |

Returns

| Type | Description |
| --- | --- |
| `bool` | `True` if the path exists, `False` otherwise. |

Raises

| Type | Description |
| --- | --- |
| `MlflowException` | If the lookup itself fails, e.g. on a connection, authentication or server error. Only a definitive "this does not exist" answer from MLflow is reported as `False`. |

#### method `get_dir`

```python
def get_dir(
    remote_paths: PosixPathType | Iterable[PosixPathType],
    local_dir: PathType,
    mlflow_instance: ModuleType | None = None,
) -> Path
```

Copy many files from remote storage to local storage.

> **Note**
> An MLflow download is staged next to the destination, so a large artifact needs free space on the destination's own filesystem rather than in `$TMPDIR`.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `remote_paths` | `PosixPathType | Iterable[PosixPathType]` | Either a path specifying a directory to walk, or an iterable of files that may be in different directories. | required |
| `local_dir` | `PathType` | Path to the local directory. | required |
| `mlflow_instance` | `ModuleType | None` | MLflow instance to use when downloading from an active run. | `None` |

Returns

| Type | Description |
| --- | --- |
| `Path` | Path to the downloaded directory. |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | If using MLflow and the run cannot be resolved. |

#### method `get_file`

```python
def get_file(
    remote_path: PosixPathType,
    local_path: PathType,
    mlflow_instance: ModuleType | None = None,
) -> Path
```

Copy a single file from remote storage.

> **Note**
> An MLflow download is staged next to the destination, so a large artifact needs free space on the destination's own filesystem rather than in `$TMPDIR`.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `remote_path` | `PosixPathType` | Relative path to the remote file. | required |
| `local_path` | `PathType` | Path to the local file. | required |
| `mlflow_instance` | `ModuleType | None` | MLflow instance to use when downloading from an active run. | `None` |

Returns

| Type | Description |
| --- | --- |
| `Path` | Path to the downloaded file. |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | If using MLflow and either no relative artifact path is specified or the run cannot be resolved. |

#### method `get_file_uuid`

```python
def get_file_uuid(path: PathType, local: bool = False) -> str
```

Read a file and returns the (unique) UUID generated from file bytes.

> **Note**
> The file is hashed in chunks, so memory use does not grow with its size. MLflow is the exception: its artifacts are downloaded through `read_to_byte_buffer`, which holds the whole file in memory before hashing begins.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `path` | `PathType` | Relative path to the remote file, or a local path when `local` is `True`. | required |
| `local` | `bool` | Specifies a local path as opposed to a remote path. | `False` |

Returns

| Type | Description |
| --- | --- |
| `str` | UUID generated from the file bytes. |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | If using MLflow and either no relative artifact path is specified or the run cannot be resolved. |

#### method `get_file_uuids`

```python
def get_file_uuids(paths: Iterable[PathType], local: bool = False) -> dict[str, str]
```

Compute the UUIDs for all files stored in the filesystem.

> **Note**
> The files are hashed concurrently, so the memory bound of `get_file_uuid` applies once per thread in the pool.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `paths` | `Iterable[PathType]` | Relative remote paths, or local paths when `local` is `True`. | required |
| `local` | `bool` | Specifies local paths as opposed to remote paths. | `False` |

Returns

| Type | Description |
| --- | --- |
| `dict[str, str]` | Dictionary mapping paths to their UUIDs. |

#### static method `get_protocol`

```python
def get_protocol(path: str) -> str
```

Extract the detected protocol from a path.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `path` | `str` | Path optionally containing the protocol. | required |

Returns

| Type | Description |
| --- | --- |
| `str` | Detected protocol. Defaults to `"file"` if no protocol is specified. |

#### method `init_fsspec_filesystem`

```python
def init_fsspec_filesystem() -> fsspec.AbstractFileSystem
```

Initialize an `fsspec` filesystem for the configured protocol.

Returns

| Type | Description |
| --- | --- |
| `fsspec.AbstractFileSystem` | Initialized `fsspec` filesystem. |

Raises

| Type | Description |
| --- | --- |
| `NotImplementedError` | If the protocol is not supported by `fsspec`. |
| `RuntimeError` | If the credentials for the protocol are not properly set in environment variables. |

#### method `is_directory`

```python
def is_directory(remote_path: PosixPathType) -> bool
```

Check whether the given remote path is a directory.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `remote_path` | `PosixPathType` | Relative path to the remote path. | required |

Returns

| Type | Description |
| --- | --- |
| `bool` | `True` if the path is a directory, `False` otherwise. |

Raises

| Type | Description |
| --- | --- |
| `FileNotFoundError` | If the path cannot be inspected on an `fsspec` filesystem. |
| `MlflowException` | If the MLflow run cannot be inspected, e.g. because it does not exist. |

#### method `put_bytes`

```python
def put_bytes(
    file_bytes: bytes,
    remote_path: PosixPathType,
    mlflow_instance: ModuleType | None = None,
)
```

Upload a file to remote storage directly from file bytes.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `file_bytes` | `bytes` | File contents to upload. | required |
| `remote_path` | `PosixPathType` | Relative path to the remote file. | required |
| `mlflow_instance` | `ModuleType | None` | MLflow instance to use when uploading to an active run. | `None` |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | If using MLflow and either no relative artifact path is specified or the run cannot be resolved. |

#### method `put_dir`

```python
def put_dir(
    local_paths: PathType | Iterable[PathType],
    remote_dir: PosixPathType,
    uuid_dict: dict[str, str] | None = None,
    mlflow_instance: ModuleType | None = None,
    copy_contents: bool = False,
) -> dict[str, str] | None
```

Upload files to remote storage.

> **Note**
> A directory is uploaded to MLflow in one call and is never staged. Passing individual files uploads them one by one through `put_file` instead, so with `uuid_dict` set the staging described there applies to each of them.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `local_paths` | `PathType | Iterable[PathType]` | Either a path specifying a directory to walk, or an iterable of files that may be in different directories. | required |
| `remote_dir` | `PosixPathType` | Relative path to the remote directory. | required |
| `uuid_dict` | `dict[str, str] | None` | Stores paths as keys and corresponding UUIDs as values to replace the file basename. | `None` |
| `mlflow_instance` | `ModuleType | None` | MLflow instance to use when uploading to an active run. | `None` |
| `copy_contents` | `bool` | If `True`, only copy the contents of the folder specified in `local_paths`. | `False` |

Returns

| Type | Description |
| --- | --- |
| `dict[str, str] | None` | Mapping of local paths to remote paths if `local_paths` is an iterable of files, otherwise `None`. |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | 1. - `If`local_paths`is a single path but not a`: directory. 2. - `If uploading to an active MLflow run without an`: MLflow instance. |

#### method `put_file`

```python
def put_file(
    local_path: PathType,
    remote_path: PosixPathType,
    mlflow_instance: ModuleType | None = None,
) -> str
```

Copy a single file to remote storage.

> **Note**
> MLflow stores a file under its local base name, so uploading under a different one is staged through a temporary copy. It is placed next to the source, meaning a large artifact needs free space on the source's own filesystem rather than in `$TMPDIR`. If that directory is not writable the staging falls back to `$TMPDIR`, which on most Linux distributions is a RAM-backed `tmpfs`, so a large artifact may then fail with `No space left on device`.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `local_path` | `PathType` | Path to the local file. | required |
| `remote_path` | `PosixPathType` | Relative path to the remote file. | required |
| `mlflow_instance` | `ModuleType | None` | MLflow instance to use when uploading to an active run. | `None` |

Returns

| Type | Description |
| --- | --- |
| `str` | Full remote path of the uploaded file. |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | If using MLflow and there is no active run or no MLflow instance provided. |

#### method `read_text`

```python
def read_text(remote_path: PosixPathType) -> str | bytes
```

Read a file into a string.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `remote_path` | `PosixPathType` | Relative path to the remote file. | required |

Returns

| Type | Description |
| --- | --- |
| `str | bytes` | The contents of the file. |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | If using MLflow and either no relative artifact path is specified or the run cannot be resolved. |

#### method `read_to_byte_buffer`

```python
def read_to_byte_buffer(remote_path: PosixPathType | None = None) -> BytesIO
```

Read a file into a byte buffer.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `remote_path` | `PosixPathType | None` | Relative path to the remote file. If omitted, reads from `self.path`. | `None` |

Returns

| Type | Description |
| --- | --- |
| `BytesIO` | Byte buffer containing the file contents. |

Raises

 * `ValueError`: 1. If using MLflow but no relative artifact path is specified.
    2. If using MLflow but the run cannot be resolved.

#### static method `split_full_path`

```python
def split_full_path(path: PathType) -> tuple[str, str]
```

Split the full path into protocol and absolute path.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `path` | `PathType` | Full path optionally containing the protocol. | required |

Returns

| Type | Description |
| --- | --- |
| `tuple[str, str]` | The used protocol and absolute path. |

#### static method `upload`

```python
def upload(local_path: PathType, url: str, tracking_uri: str | None = None)
```

Upload file or directory to remote storage.

Useful for uploading a single local object without having to create a [LuxonisFileSystem](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) instance.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `local_path` | `PathType` | Path to the local file or directory. | required |
| `url` | `str` | URL to the remote file or directory. | required |
| `tracking_uri` | `str | None` | MLflow tracking URI to use for `mlflow://` URLs. | `None` |

#### method `walk_dir`

```python
def walk_dir(
    remote_dir: PosixPathType,
    recursive: bool = True,
    typ: Literal['file', 'directory', 'all'] = 'file',
) -> Iterator[str]
```

Walk through the individual files in a remote directory.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `remote_dir` | `PosixPathType` | Relative path to the remote directory. | required |
| `recursive` | `bool` | If True, walks through the directory recursively. Defaults to True. | `True` |
| `typ` | `Literal['file', 'directory', 'all']` | Type of entries to yield. Corresponds to the `"type"` field in fsspec's ls output. Defaults to `"file"`. | `'file'` |

Returns

| Type | Description |
| --- | --- |
| `Iterator[str]` |  |

Yields

| Type | Description |
| --- | --- |
|  | Relative paths to the files in the remote directory. |

### class `PutFile`

```python
class PutFile(Protocol)
```

Protocol for the `put_file` plugins.

## Module Attributes

| Name | Type | Description |
| --- | --- | --- |
| [`PUT_FILE_REGISTRY`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) | `Registry[PutFile]` |  |

### constant `PUT_FILE_REGISTRY`

```python
PUT_FILE_REGISTRY: Registry[PutFile] = Registry(name='put_file')
```
