# ファイルシステムAPI

`HfFileSystem` クラスは、[`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) をベースとした Hugging Face Hub 向けの Pythonic なファイルインターフェースを提供します。

## HfFileSystem[[huggingface_hub.HfFileSystem]]

`HfFileSystem` は [fsspec](https://filesystem-spec.readthedocs.io/en/latest/) をベースにしているため、fsspec が提供するほとんどの API と互換性があります。詳細については、[こちらのガイド](../guides/hf_file_system)と fsspec の [API リファレンス](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem)を参照してください。

#### huggingface_hub.HfFileSystem[[huggingface_hub.HfFileSystem]]

```python
huggingface_hub.HfFileSystem(*args, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L370)

**パラメータ:**

endpoint (`str`, *任意*) : Hub のエンドポイント。デフォルトは です。

token (`bool` または `str`、*省略可能*) : 有効なユーザーアクセストークン（文字列）。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authentication を参照）。認証を無効にするには、`False` を渡します。

block_size (`int`, *任意*) : ファイルの読み書きに使用するブロックサイズ。

expand_info (`bool`, *任意*) : ファイルの情報を展開するかどうか。

max_workers (`int`, *任意*) : 大規模なディレクトリを並列で一覧表示するために使用される同時リクエストの最大数（[find()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_file_system#huggingface_hub.HfFileSystem.find)を参照）。デフォルト値は16です。並列一覧表示を無効にする場合は1に設定してください。

live_follow (`bool`, *オプション*) : Hub 上でバケットのファイル変更が発生した際に追従し、手動で [HfFileSystem.invalidate_cache()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_file_system#huggingface_hub.HfFileSystem.invalidate_cache) を呼び出さなくてもキャッシュされた一覧が最新の状態を維持できるようにするかどうか。有効にすると、バケットの一覧を取得する際に、そのバケットの Hub イベントフィードへのバックグラウンド接続が開かれます。モデル、データセット、スペースのリポジトリには影響しません（Hub はそれらの変更を配信しないため）。

- ****storage_options** (`dict`, *任意*) : ファイルシステム用の追加オプション。[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.__init__)を参照してください。

リモートのHugging Face Hubリポジトリをローカルファイルシステムのようにアクセスします。

> [!WARNING]
> [HfFileSystem](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_file_system#huggingface_hub.HfFileSystem) は fsspec 互換性を提供しており、これを必要とするライブラリ（`pandas` で Hugging Face のデータセットを直接読み込む場合など）に便利です。ただし、この互換性レイヤーにより追加のオーバーヘッドが発生します。パフォーマンスと信頼性を高めるため、可能な場合は `HfApi` のメソッドを使用することをお勧めします。

ファイルシステムは`hf://`プロトコルのパスをサポートしており、以下のURLスキームに従います:

* Models、Datasets、Spacesリポジトリ:

```
hf://<repo-id>[@<revision>]/<path/in/repo>
hf://datasets/<repo-id>[@<revision>]/<path/in/repo>
hf://spaces/<repo-id>[@<revision>]/<path/in/repo>
```

* Buckets （汎用ストレージ）：

```
hf://buckets/<bucket-id>/<path/in/bucket>
```

注: [HfFileSystem](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_file_system#huggingface_hub.HfFileSystem)を直接使用する場合、パスに`hf://`プロトコルプレフィックスを付けることは任意です。

使用方法:

```python
>>> from huggingface_hub import hffs

>>> # List files
>>> hffs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> hffs.ls("datasets/my-username/my-dataset", detail=False)
['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']

>>> # Read/write files
>>> with hffs.open("my-username/my-model/pytorch_model.bin") as f:
...     data = f.read()
>>> with hffs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
...     f.write(data)
```

認証用のトークンを指定します:
```python
>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(token=token)
```

#### cp_file[[huggingface_hub.HfFileSystem.cp_file]]

```python
cp_file(path1: str, path2: str, revision: str | None = None, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1115)

**パラメータ:**

path1 (`str`) : コピー元のソースパス。

path2 (`str`) : コピー先のパス。

revision (`str`, *任意*) : コピー元の git リビジョン。

リポジトリ内またはリポジトリ間でファイルをコピーするか、バケットにコピーします。

> [!WARNING]
> 注: 可能な場合は、パフォーマンス向上のため`HfApi.upload_file()`を使用してください。

#### 存在する[[huggingface_hub.HfFileSystem.exists]]

```python
exists(path, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1336)

**パラメータ:**

path (`str`) : 確認するパス。

**戻り値:** `bool`

ファイルが存在する場合はTrue、それ以外の場合はFalse。

ファイルが存在するかどうかを確認します。

詳細については、[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.exists)を参照してください。

> [!WARNING]
> 注: 可能な場合は、パフォーマンス向上のため`HfApi.file_exists()`を使用してください。

#### 検索[[huggingface_hub.HfFileSystem.find]]

```python
find(path: str, maxdepth: int | None = None, withdirs: bool = False, detail: bool = False, refresh: bool = False, revision: str | None = None, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1051)

**パラメータ:**

path (`str`) : ファイルを列挙するルートパス。

maxdepth (`int`, *任意*) : サブディレクトリに降下する最大深度。

withdirs (`bool`, *任意*) : 出力にディレクトリパスを含めるかどうか。デフォルトは False です。

detail (`bool`, *任意*) : True の場合、パスからファイル情報へのマッピングを含む dict を返します。デフォルトは False です。

refresh (`bool`, *任意*) : True の場合、キャッシュをバイパスして最新のデータを取得します。デフォルトは False です。

revision (`str`, *任意*) : リストを取得する git リビジョン。

**戻り値:** `Union[list[str], dict[str, dict[str, Any]]]`

パスのリストまたはファイル情報の辞書。

パス以下のすべてのファイルをリスト表示します。

詳細については、[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.find)を参照してください。

> [!TIP]
> 大規模なリポジトリは、Hubの`tree`エンドポイントのカーソルベースのページネーションを回避するために、ディレクトリごとに並列で一覧表示されます。この設定は、[HfFileSystem](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_file_system#huggingface_hub.HfFileSystem)の`max_workers`引数で調整できます。

#### get_file[[huggingface_hub.HfFileSystem.get_file]]

```python
get_file(rpath, lpath = None, callback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>, outfile = None, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1444)

**パラメータ:**

rpath (`str`) : ダウンロード元のリモートパス。

lpath (`str`, *任意*) : ダウンロード先ローカルパス。`outfile` が指定されている場合は省略できます。

callback (`Callback`, *optional*) : ダウンロードの進捗を追跡するための任意のコールバック。デフォルトではコールバックなしです。

outfile (`IO`, *任意*) : 書き出し先となる任意のファイルライクオブジェクト。指定された場合、`lpath` は無視されます。

単一のリモートファイルをローカルにコピーします。

> [!WARNING]
> 注: 可能な場合は、パフォーマンス向上のため`HfApi.hf_hub_download()`または`HfApi.download_bucket_files`を使用してください。

#### glob[[huggingface_hub.HfFileSystem.glob]]

```python
glob(path: str, maxdepth: int | None = None, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1033)

**パラメータ:**

path (`str`) : 一致させるパスパターン。

maxdepth (`int`, *optional*) : ディレクトリに降下する最大深度。デフォルトでは制限なし。

**戻り値:** `list[str]`

パターンに一致するパスのリスト。

globマッチングでファイルを検索します。

詳細については、[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.glob)を参照してください。

#### info[[huggingface_hub.HfFileSystem.info]]

```python
info(path: str, refresh: bool = False, revision: str | None = None, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1226)

**パラメータ:**

path (`str`) : 情報取得対象のパス。

refresh (`bool`, *任意*) : True の場合、キャッシュをバイパスして最新のデータを取得します。デフォルトは False です。

revision (`str`, *任意*) : 情報取得元の git リビジョン。

**戻り値:** `dict[str, Any]`

ファイル情報（タイプ、サイズ、コミット情報など）を含む辞書。

ファイルまたはディレクトリに関する情報を取得します。

詳細については、[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.info)を参照してください。

> [!WARNING]
> 注: 可能な場合は、パフォーマンス向上のため`HfApi.get_paths_info()`または`HfApi.repo_info()`を使用してください(バケットの場合は`HfApi.get_bucket_paths_info()`または`HfApi.bucket_info()`)

#### invalidate_cache[[huggingface_hub.HfFileSystem.invalidate_cache]]

```python
invalidate_cache(path: str | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L599)

**パラメータ:**

path (`str`, *任意*) : キャッシュからクリアするパス。指定しない場合、キャッシュ全体をクリアします。

指定されたパスのキャッシュをクリアします。

詳細については、[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.invalidate_cache)を参照してください。

#### isdir[[huggingface_hub.HfFileSystem.isdir]]

```python
isdir(path)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1361)

**パラメータ:**

path (`str`) : 確認するパス。

**戻り値:** `bool`

path がディレクトリの場合に True、それ以外の場合は False を返します。

パスがディレクトリかどうかを確認します。

詳細については、[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.isdir)を参照してください。

#### isfile[[huggingface_hub.HfFileSystem.isfile]]

```python
isfile(path)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1379)

**パラメータ:**

path (`str`) : 確認するパス。

**戻り値:** `bool`

path がファイルの場合は True、それ以外の場合は False。

パスがファイルかどうかを確認します。

詳細については、[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.isfile)を参照してください。

#### ls[[huggingface_hub.HfFileSystem.ls]]

```python
ls(path: str, detail: bool = True, refresh: bool = False, revision: str | None = None, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L788)

**パラメータ:**

path (`str`) : ディレクトリへのパス。

detail (`bool`, *任意*) : True の場合、ファイル情報を含む辞書のリストを返します。False の場合、ファイルパスのリストを返します。デフォルトは True です。

refresh (`bool`, *任意*) : True の場合、キャッシュをバイパスして最新のデータを取得します。デフォルトは False です。

revision (`str`, *任意*) : リストを取得する git リビジョン。

**戻り値:** `list[Union[str, dict[str, Any]]]`

ファイルパスのリスト（detail=Falseの場合）またはファイル情報辞書のリスト（detail=Trueの場合）。

ディレクトリの内容をリスト表示します。

詳細については、[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.ls)を参照してください。

> [!WARNING]
> 注: 可能な場合は、パフォーマンス向上のため`HfApi.list_repo_tree()`を使用してください。

#### 修正[[huggingface_hub.HfFileSystem.modified]]

```python
modified(path: str, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1201)

**パラメータ:**

path (`str`) : ファイルへのパス。

**戻り値:** `datetime`

ファイルの最終変更時刻。

ファイルの最終変更時刻を取得します。

詳細については、[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.modified)を参照してください。

#### resolve_path[[huggingface_hub.HfFileSystem.resolve_path]]

```python
resolve_path(path: str, revision: str | None = None)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L520)

**パラメータ:**

path (`str`) : 解決するパス。

revision (`str`, *任意*) : 解決するリポジトリのリビジョンです。デフォルトでは、パスで指定されたリビジョンになります。

**戻り値:** `HfFileSystemResolvedPath`

`repo_type`、`repo_id`、`revision`、`path_in_repo` を含む解決済みパス情報。

**例外:** ``ValueError`` または ``NotImplementedError``

- ``ValueError`` -- パスに矛盾するリビジョン情報が含まれている場合。
- ``NotImplementedError`` -- リポジトリのリスト表示を試みた場合。

Hugging Face のファイルシステムパスを各コンポーネントに分解します。

#### rm[[huggingface_hub.HfFileSystem.rm]]

```python
rm(path: str, recursive: bool = False, maxdepth: int | None = None, revision: str | None = None, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L738)

**パラメータ:**

path (`str`) : 削除するパス。

recursive (`bool`, *任意*) : True の場合、ディレクトリとその中身すべてを削除します。デフォルトは False です。

maxdepth (`int`, *optional*) : 再帰的に削除する際に訪れるサブディレクトリの最大数。

revision (`str`, *任意*) : 削除元の git リビジョン。

リポジトリからファイルを削除します。

詳細については、[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.rm)を参照してください。

> [!WARNING]
> 注: 可能な場合は、パフォーマンス向上のため`HfApi.delete_file()`を使用してください。

#### URL[[huggingface_hub.HfFileSystem.url]]

```python
url(path: str)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1397)

**パラメータ:**

path (`str`) : URL を取得するパス。

**戻り値:** `str`

Hub上のファイルまたはディレクトリにアクセスするためのHTTP URL。

指定されたパスのHTTP URLを取得します。

#### walk[[huggingface_hub.HfFileSystem.walk]]

```python
walk(path: str, *args, **kwargs)
```

[ソース](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1017)

**パラメータ:**

path (`str`) : ファイルを列挙するルートパス。

**戻り値:** `Iterator[tuple[str, list[str], list[str]]]`

(path, ディレクトリ名のリスト, ファイル名のリスト)のタプルのイテレータ。

指定されたパス以下のすべてのファイルを返します。

詳細については、[fsspecのドキュメント](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.walk)を参照してください。