# filesystem

Python API: `luxonis_ml.utils.filesystem`

## 类

### FSType

文件系统后端类型。

#### 属性

##### FSSPEC

fsspec 兼容文件系统。

##### MLFLOW

MLflow 工件存储。

### LuxonisFileSystem

远程和本地源的抽象。

此类别为不同存储后端（包括本地文件系统、S3、GCS 和 MLflow 工件存储）的文件操作提供统一接口。后端通过 URL 协议选择：

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

没有协议的路径被视为本地路径。对于 MLflow，`<artifact_path>` 是可选的，默认为运行的工件根目录，因此 `mlflow://<experiment_id>/<run_id>` 本身就是一个有效的目的地。裸 `mlflow://`
将文件系统绑定到当前活动的运行，并且需要 `allow_active_mlflow_run=True`。MLflow 工件无法删除，因此 `delete_*` 方法会为它们引发 `NotImplementedError`。

为了获得更大的灵活性，用户可以在 `PUT_FILE_REGISTRY` 中注册 `put_file` 方法的自定义实现。然后，在初始化 `LuxonisFileSystem` 时，可以将其名称作为 `put_file_plugin`
参数传递。这允许自定义上传逻辑，例如上传前的额外处理或与其他服务的集成。

> **示例**
> ```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
```

上传到特定 MLflow 运行的工件存储，该运行返回新工件的 URL。

```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"
```

#### 方法

##### 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):
```

初始化 `LuxonisFileSystem`。

参数

 * `path` (`str`): 输入路径，由协议和路径组成，或仅由本地文件的路径组成。MLflow 路径的形式为 `mlflow://<experiment_id>/<run_id>/<artifact_path>`，其中工件路径是可选的，或者是一个裸 `mlflow://` 以使用活动运行。
 * `allow_active_mlflow_run` (`bool | None`): 是否允许对活动 MLflow 运行进行操作。
 * `allow_local` (`bool | None`): 是否允许对本地文件系统进行操作。
 * `cache_storage` (`str | None`): `fsspec` `filecache` 目录的路径，仅由 `s3://` 和 `gcs://` 后端使用。如果未设置，则不使用缓存，并且对于 `file://` 和 `mlflow://`，会发出警告并忽略。
 * `put_file_plugin` (`str | None`): [PUT_FILE_REGISTRY](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) 中注册函数的名称，用于代替 [LuxonisFileSystem.put_file](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md)。注册函数必须符合 [PutFile](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) 协议。
 * `tracking_uri` (`str | None`): 要使用的 MLflow 跟踪 URI。如果省略，则使用环境中的 `MLFLOW_TRACKING_URI`。

引发

 * `ValueError`: 1. 如果协议不受支持。
    2. 如果协议是 `"file"` 但不允许本地文件。
    * `如果协议是`"mlflow"`但未指定 MLflow 路径`：并且不允许使用活动 MLflow 运行。
    * `如果协议是`"mlflow"`但环境变量中没有`：`"MLFLOW_TRACKING_URI"`。

##### delete_dir

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

从远程存储中删除目录及其所有内容。

参数

 * `remote_dir` (`PosixPathType`): 远程目录的相对路径。
 * `allow_delete_parent` (`bool`): 是否允许删除父目录。

引发

 * `ValueError`: 如果未指定目录且不允许删除父目录。
 * `NotImplementedError`: 如果使用 MLflow，其工件无法删除。

##### delete_file

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

从远程存储中删除单个文件。

参数

 * `remote_path` (`PosixPathType`): 远程文件的相对路径。

引发

 * `NotImplementedError`: 如果使用 MLflow，其工件无法删除。

##### delete_files

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

从远程存储中删除多个文件。

参数

 * `remote_paths` (`list[PosixPathType]`): 远程文件的相对路径。

引发

 * `NotImplementedError`: 如果使用 MLflow，其工件无法删除。

##### download

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

从远程存储下载文件或目录。

旨在下载单个远程对象，而无需创建 `LuxonisFileSystem` 实例。

参数

 * `url` (`str`): 文件或目录的 URL。
 * `dest` (`PathType | None`): 目标目录。如果为 `None`，则使用当前工作目录。
 * `tracking_uri` (`str | None`): 用于 `mlflow://` URL 的 MLflow 跟踪 URI。

返回

 * `Path`: 下载的文件或目录的路径。当目标已存在时，数据嵌套在其中并返回嵌套路径。

##### exists

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

检查给定远程路径是否存在。

参数

 * `remote_path` (`PosixPathType`): 远程文件的相对路径。默认为空字符串，表示文件系统的根路径。

返回

 * `bool`: 如果路径存在，则为 `True`，否则为 `False`。

引发

 * `MlflowException`: 如果查找本身失败，例如连接、身份验证或服务器错误。只有 MLflow 明确的“此不存在”答案才报告为 `False`。

##### get_dir

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

将许多文件从远程存储复制到本地存储。

> **注意**
> MLflow 下载在目标旁边进行暂存，因此大型工件需要在目标自己的文件系统而不是 `$TMPDIR` 中有可用空间。

参数

 * `remote_paths` (`PosixPathType | Iterable[PosixPathType]`): 指定要遍历的目录的路径，或可能位于不同目录中的文件的可迭代对象。
 * `local_dir` (`PathType`): 本地目录的路径。
 * `mlflow_instance` (`ModuleType | None`): 从活动运行下载时要使用的 MLflow 实例。

返回

 * `Path`: 下载的目录的路径。

引发

 * `ValueError`: 如果使用 MLflow 且无法解析运行。

##### get_file

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

从远程存储复制单个文件。

> **注意**
> MLflow 下载在目标旁边进行暂存，因此大型工件需要在目标自己的文件系统而不是 `$TMPDIR` 中有可用空间。

参数

 * `remote_path` (`PosixPathType`): 远程文件的相对路径。
 * `local_path` (`PathType`): 本地文件的路径。
 * `mlflow_instance` (`ModuleType | None`): 从活动运行下载时要使用的 MLflow 实例。

返回

 * `Path`: 下载的文件路径。

引发

 * `ValueError`: 如果使用 MLflow 且未指定相对工件路径或无法解析运行。

##### get_file_uuid

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

读取文件并返回从文件字节生成的（唯一）UUID。

> **注意**
> 文件分块哈希，因此内存使用量不会随其大小而增长。MLflow 是一个例外：其工件通过 `read_to_byte_buffer` 下载，该方法在哈希开始之前将整个文件保存在内存中。

参数

 * `path` (`PathType`): 远程文件的相对路径，或当 `local` 为 `True` 时的本地路径。
 * `local` (`bool`): 指定本地路径而不是远程路径。

返回

 * `str`: 从文件字节生成的 UUID。

引发

 * `ValueError`: 如果使用 MLflow 且未指定相对工件路径或无法解析运行。

##### get_file_uuids

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

计算文件系统中存储的所有文件的 UUID。

> **注意**
> 文件并发哈希，因此 `get_file_uuid` 的内存限制在池中的每个线程上应用一次。

参数

 * `paths` (`Iterable[PathType]`): 相对远程路径，或当 `local` 为 `True` 时的本地路径。
 * `local` (`bool`): 指定本地路径而不是远程路径。

返回

 * `dict[str, str]`: 将路径映射到其 UUID 的字典。

##### get_protocol

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

从路径中提取检测到的协议。

参数

 * `path` (`str`): 可选包含协议的路径。

返回

 * `str`: 检测到的协议。如果未指定协议，则默认为 `"file"`。

##### init_fsspec_filesystem

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

为配置的协议初始化 `fsspec` 文件系统。

返回

 * `fsspec.AbstractFileSystem`: 初始化的 `fsspec` 文件系统。

引发

 * `NotImplementedError`: 如果协议不受 `fsspec` 支持。
 * `RuntimeError`: 如果协议的凭据未在环境变量中正确设置。

##### is_directory

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

检查给定远程路径是否为目录。

参数

 * `remote_path` (`PosixPathType`): 远程路径的相对路径。

返回

 * `bool`: 如果路径是目录，则为 `True`，否则为 `False`。

引发

 * `FileNotFoundError`: 如果无法在 `fsspec` 文件系统上检查路径。
 * `MlflowException`: 如果无法检查 MLflow 运行，例如因为它不存在。

##### put_bytes

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

直接从文件字节将文件上传到远程存储。

参数

 * `file_bytes` (`bytes`): 要上传的文件内容。
 * `remote_path` (`PosixPathType`): 远程文件的相对路径。
 * `mlflow_instance` (`ModuleType | None`): 上传到活动运行时要使用的 MLflow 实例。

引发

 * `ValueError`: 如果使用 MLflow 且未指定相对工件路径或无法解析运行。

##### 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:
```

将文件上传到远程存储。

> **注意**
> 目录在一次调用中上传到 MLflow，并且从不暂存。传递单个文件会通过 `put_file` 一个接一个地上传它们，因此如果设置了 `uuid_dict`，则其中描述的暂存适用于每个文件。

参数

 * `local_paths` (`PathType | Iterable[PathType]`): 指定要遍历的目录的路径，或可能位于不同目录中的文件的可迭代对象。
 * `remote_dir` (`PosixPathType`): 远程目录的相对路径。
 * `uuid_dict` (`dict[str, str] | None`): 将路径存储为键，将相应的 UUID 存储为值以替换文件基本名称。
 * `mlflow_instance` (`ModuleType | None`): 上传到活动运行时要使用的 MLflow 实例。
 * `copy_contents` (`bool`): 如果为 `True`，则仅复制 `local_paths` 中指定的文件夹内容。

返回

 * `dict[str, str] | None`: 如果 `local_paths` 是文件的可迭代对象，则为本地路径到远程路径的映射，否则为 `None`。

引发

 * `ValueError`: 1. * `如果`local_paths`是单个路径但不是`：目录。
    * `如果上传到活动 MLflow 运行但没有`：MLflow 实例。

##### put_file

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

将单个文件复制到远程存储。

> **注意**
> MLflow 将文件存储在其本地基本名称下，因此以不同名称上传会通过临时副本进行暂存。它放置在源旁边，这意味着大型工件需要在源自己的文件系统而不是 `$TMPDIR` 中有可用空间。如果该目录不可写，则暂存会回退到 `$TMPDIR`，这在大多数 Linux 发行版上是 RAM 支持的 `tmpfs`，因此大型工件可能会因 `No space left on device` 而失败。

参数

 * `local_path` (`PathType`): 本地文件的路径。
 * `remote_path` (`PosixPathType`): 远程文件的相对路径。
 * `mlflow_instance` (`ModuleType | None`): 上传到活动运行时要使用的 MLflow 实例。

返回

 * `str`: 上传文件的完整远程路径。

引发

 * `ValueError`: 如果使用 MLflow 且没有活动运行或未提供 MLflow 实例。

##### read_text

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

将文件读取为字符串。

参数

 * `remote_path` (`PosixPathType`): 远程文件的相对路径。

返回

 * `str | bytes`: 文件内容。

引发

 * `ValueError`: 如果使用 MLflow 且未指定相对工件路径或无法解析运行。

##### read_to_byte_buffer

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

将文件读取到字节缓冲区。

参数

 * `remote_path` (`PosixPathType | None`): 远程文件的相对路径。如果省略，则从 `self.path` 读取。

返回

 * `BytesIO`: 包含文件内容的字节缓冲区。

引发

 * `ValueError`: 1. 如果使用 MLflow 但未指定相对工件路径。
    2. 如果使用 MLflow 但无法解析运行。

##### split_full_path

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

将完整路径拆分为协议和绝对路径。

参数

 * `path` (`PathType`): 可选包含协议的完整路径。

返回

 * `tuple[str, str]`: 使用的协议和绝对路径。

##### upload

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

将文件或目录上传到远程存储。

对于上传单个本地对象而无需创建 [LuxonisFileSystem](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/utils/filesystem.md) 实例很有用。

参数

 * `local_path` (`PathType`): 本地文件或目录的路径。
 * `url` (`str`): 远程文件或目录的 URL。
 * `tracking_uri` (`str | None`): 用于 `mlflow://` URL 的 MLflow 跟踪 URI。

#### walk_dir

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

遍历远程目录中的单个文件。

参数

 * `remote_dir` (`PosixPathType`): 远程目录的相对路径。
 * `recursive` (`bool`): 如果为 True，则递归遍历目录。默认为 True。
 * `typ` (`Literal['file', 'directory', 'all']`): 要生成的条目类型。对应于 fsspec 的 ls 输出中的 `"type"` 字段。默认为 `"file"`。

返回

 * `Iterator[str]`

生成

 * 远程目录中文件的相对路径。

#### 属性

##### artifact_path

MLflow 工件路径。

返回

 * 相对于运行工件根目录的工件路径，如果文件系统不是 MLflow 文件系统或未给出工件路径，则为 `None`。

##### experiment_id

MLflow 实验 ID。

返回

 * 实验 ID，如果文件系统不是 MLflow 文件系统或实验未知，则为 `None`。

##### full_path

完整远程路径。

返回

 * 以协议为前缀的完整远程路径。

##### is_fsspec

检查文件系统是否使用 fsspec。

返回

 * 如果文件系统使用 fsspec，则为 `True`。

##### is_mlflow

检查文件系统是否为 MLflow 文件系统。

返回

 * 如果文件系统是 MLflow 文件系统，则为 `True`。

##### protocol

返回文件系统的协议。

@type: str

##### run_id

MLflow 运行 ID。

返回

 * 运行 ID，如果文件系统不是 MLflow 文件系统或运行未知，则为 `None`。

##### tracking_uri

MLflow 跟踪 URI。

返回

 * 跟踪 URI，如果文件系统不是 MLflow 文件系统，则为 `None`。

### PutFile

`put_file` 插件的协议。

## 属性

### PUT_FILE_REGISTRY
