# API Filesystem

Kelas `HfFileSystem` menyediakan antarmuka file yang pythonic ke Hugging Face Hub berdasarkan [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/).

## HfFileSystem[[huggingface_hub.HfFileSystem]]

`HfFileSystem` didasarkan pada [fsspec](https://filesystem-spec.readthedocs.io/en/latest/), sehingga kompatibel dengan sebagian besar API yang ditawarkannya. Untuk detail lebih lanjut, lihat [panduan kami](../guides/hf_file_system) dan [API Reference](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem) fsspec.

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

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

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

**Parameter:**

endpoint (`str`, *opsional*) : Endpoint dari Hub. Bawaan ke .

token (`bool` atau `str`, *opsional*) : Token akses pengguna yang valid (string). Secara default menggunakan token yang disimpan secara lokal, yang merupakan metode autentikasi yang direkomendasikan (lihat https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Untuk menonaktifkan autentikasi, berikan `False`.

block_size (`int`, *opsional*) : Ukuran blok untuk membaca dan menulis file.

expand_info (`bool`, *opsional*) : Apakah akan memperluas informasi file.

max_workers (`int`, *opsional*) : Jumlah maksimum permintaan konkuren yang digunakan untuk mendaftar direktori besar secara paralel (lihat [find()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem.find)). Bawaan adalah 16. Atur ke 1 untuk menonaktifkan pendaftaran paralel.

live_follow (`bool`, *opsional*) : Apakah akan mengikuti perubahan file di bucket sesuai dengan kejadian di Hub, sehingga daftar cache tetap segar tanpa perlu pemanggilan manual [HfFileSystem.invalidate_cache()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem.invalidate_cache). Saat diaktifkan, melisting sebuah bucket akan membuka koneksi latar belakang ke feed event Hub untuk bucket tersebut. Tidak berdampak pada repositori model, dataset, dan space (Hub tidak menyediakan feed perubahan untuk jenis repositori tersebut).

- ****storage_options** (`dict`, *opsional*) : Opsi tambahan untuk sistem file. Lihat [dokumentasi fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.__init__).

Akses repositori Hugging Face Hub jarak jauh seolah-olah itu adalah sistem file lokal.

> [!WARNING]
> [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem) menyediakan kompatibilitas fsspec, yang berguna untuk pustaka yang membutuhkannya (misalnya, membaca dataset Hugging Face secara langsung dengan `pandas`). Namun, lapisan kompatibilitas ini memperkenalkan overhead tambahan. Untuk kinerja dan keandalan yang lebih baik, disarankan untuk menggunakan metode `HfApi` ketika memungkinkan.

Sistem file mendukung jalur untuk protokol `hf://`, yang mengikuti skema URL berikut:

* Repositori Models, Datasets, dan 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 (penyimpanan generik):

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

Catatan: saat menggunakan [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem) secara langsung, meneruskan prefiks protokol `hf://` bersifat opsional dalam path.

Penggunaan:

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

Tentukan token untuk autentikasi:
```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)
```

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

**Parameter:**

path1 (`str`) : Path sumber untuk disalin.

path2 (`str`) : Jalur tujuan untuk menyalin ke.

revision (`str`, *opsional*) : Revisi git yang akan disalin.

Salin file di dalam atau antar repositori, atau ke dalam bucket.

> [!WARNING]
> Catatan: Jika memungkinkan, gunakan `HfApi.upload_file()` untuk kinerja yang lebih baik.

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

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

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

**Parameter:**

path (`str`) : Path untuk diperiksa.

**Mengembalikan:** `bool`

True jika file ada, False jika tidak.

Periksa apakah file ada.

Untuk detail lebih lanjut, lihat [dokumentasi fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.exists).

> [!WARNING]
> Catatan: Jika memungkinkan, gunakan `HfApi.file_exists()` untuk kinerja yang lebih baik.

#### cari[[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)
```

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

**Parameter:**

path (`str`) : Path root untuk mendaftar file.

maxdepth (`int`, *opsional*) : Kedalaman maksimum untuk masuk ke subdirektori.

withdirs (`bool`, *opsional*) : Sertakan jalur direktori dalam output. Defaultnya False.

detail (`bool`, *opsional*) : Jika True, mengembalikan dict yang memetakan path ke informasi file. Defaultnya False.

refresh (`bool`, *opsional*) : Jika True, lewati cache dan ambil data terbaru. Bawaan adalah False.

revision (`str`, *opsional*) : Revisi git yang akan diurutkan.

**Mengembalikan:** `Union[list[str], dict[str, dict[str, Any]]]`

Daftar path atau dict informasi file.

Daftarkan semua file di bawah path.

Untuk detail lebih lanjut, lihat [dokumentasi fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.find).

> [!TIP]
> Repositori besar diurutkan per direktori, secara paralel, untuk menghindari paginasi berbasis kursor dari endpoint `tree` Hub. Sesuaikan ini dengan argumen `max_workers` dari [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem).

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

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

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

**Parameter:**

rpath (`str`) : Jalur jarak jauh untuk diunduh.

lpath (`str`, *opsional*) : Jalur lokal untuk mengunduh. Dapat diabaikan jika `outfile` disediakan.

callback (`Callback`, *opsional*) : Opsional untuk melacak progres unduhan. Bawaan adalah tanpa callback.

outfile (`IO`, *opsional*) : Objek serupa file opsional untuk ditulis. Jika disediakan, `lpath` diabaikan.

Salin satu file jarak jauh ke lokal.

> [!WARNING]
> Catatan: Jika memungkinkan, gunakan `HfApi.hf_hub_download()` atau `HfApi.download_bucket_files` untuk kinerja yang lebih baik.

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

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

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

**Parameter:**

path (`str`) : Pola path yang akan dicocokkan.

maxdepth (`int`, *opsional*) : Kedalaman maksimum untuk masuk ke dalam direktori. Secara default, tidak ada batas.

**Mengembalikan:** `list[str]`

Daftar path yang cocok dengan pola.

Cari file dengan glob-matching.

Untuk detail lebih lanjut, lihat [dokumentasi 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)
```

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

**Parameter:**

path (`str`) : Path untuk mendapatkan info.

refresh (`bool`, *opsional*) : Jika True, lewati cache dan ambil data terbaru. Bawaan adalah False.

revision (`str`, *opsional*) : Revisi git untuk diambil informasinya.

**Mengembalikan:** `dict[str, Any]`

Dictionary yang berisi informasi file (tipe, ukuran, info commit, dll.).

Dapatkan informasi tentang file atau direktori.

Untuk detail lebih lanjut, lihat [dokumentasi fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.info).

> [!WARNING]
> Catatan: Jika memungkinkan, gunakan `HfApi.get_paths_info()` atau `HfApi.repo_info()` untuk kinerja yang lebih baik (atau `HfApi.get_bucket_paths_info()` atau `HfApi.bucket_info()` untuk bucket)

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

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

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

**Parameter:**

path (`str`, *opsional*) : Path untuk dibersihkan dari cache. Jika tidak disediakan, seluruh cache akan dibersihkan.

Bersihkan cache untuk path tertentu.

Untuk detail lebih lanjut, lihat [dokumentasi fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.invalidate_cache).

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

```python
isdir(path)
```

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

**Parameter:**

path (`str`) : Path untuk diperiksa.

**Mengembalikan:** `bool`

True jika path adalah direktori, False selain itu.

Periksa apakah sebuah path adalah direktori.

Untuk detail lebih lanjut, lihat [dokumentasi fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.isdir).

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

```python
isfile(path)
```

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

**Parameter:**

path (`str`) : Path untuk diperiksa.

**Mengembalikan:** `bool`

True jika path adalah file, False selain itu.

Periksa apakah sebuah path adalah file.

Untuk detail lebih lanjut, lihat [dokumentasi 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)
```

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

**Parameter:**

path (`str`) : Path ke direktori.

detail (`bool`, *opsional*) : Jika True, mengembalikan daftar kamus yang berisi informasi file. Jika False, mengembalikan daftar jalur file. Bawaan adalah True.

refresh (`bool`, *opsional*) : Jika True, lewati cache dan ambil data terbaru. Bawaan adalah False.

revision (`str`, *opsional*) : Revisi git yang akan diurutkan.

**Mengembalikan:** `list[Union[str, dict[str, Any]]]`

Daftar jalur file (jika detail=False) atau daftar kamus informasi file (jika detail=True).

Daftarkan isi direktori.

Untuk detail lebih lanjut, lihat [dokumentasi fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.ls).

> [!WARNING]
> Catatan: Jika memungkinkan, gunakan `HfApi.list_repo_tree()` untuk kinerja yang lebih baik.

#### diubah[[huggingface_hub.HfFileSystem.modified]]

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

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

**Parameter:**

path (`str`) : Path ke file.

**Mengembalikan:** `datetime`

Waktu modifikasi terakhir file.

Dapatkan waktu modifikasi terakhir dari sebuah file.

Untuk detail lebih lanjut, lihat [dokumentasi 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)
```

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

**Parameter:**

path (`str`) : Path untuk di-resolve.

revision (`str`, *opsional*) : Revisi repo yang akan di-resolve. Secara default menggunakan revisi yang ditentukan dalam path.

**Mengembalikan:** `HfFileSystemResolvedPath`

Informasi path yang telah dipecah, berisi `repo_type`, `repo_id`, `revision`, dan `path_in_repo`.

**Mengangkat:** ``ValueError`` atau ``NotImplementedError``

- ``ValueError`` -- Jika path berisi informasi revisi yang saling bertentangan.
- ``NotImplementedError`` -- Jika mencoba membuat daftar repositori.

Menyelesaikan jalur file sistem Hugging Face menjadi komponen-komponennya.

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

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

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

**Parameter:**

path (`str`) : Path yang akan dihapus.

recursive (`bool`, *opsional*) : Jika True, hapus direktori dan seluruh isinya. Defaultnya False.

maxdepth (`int`, *opsional*) : Jumlah maksimum subdirektori yang akan dikunjungi saat penghapusan secara rekursif.

revision (`str`, *opsional*) : Revisi git yang akan dihapus.

Hapus file dari repositori.

Untuk detail lebih lanjut, lihat [dokumentasi fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.rm).

> [!WARNING]
> Catatan: Jika memungkinkan, gunakan `HfApi.delete_file()` untuk kinerja yang lebih baik.

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

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

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

**Parameter:**

path (`str`) : Path untuk mendapatkan URL.

**Mengembalikan:** `str`

URL HTTP untuk mengakses file atau direktori di Hub.

Dapatkan URL HTTP dari path yang diberikan.

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

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

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

**Parameter:**

path (`str`) : Path root untuk mendaftar file.

**Mengembalikan:** `Iterator[tuple[str, list[str], list[str]]]`

Iterator dari tuple (path, daftar nama direktori, daftar nama file).

Kembalikan semua file di bawah path yang diberikan.

Untuk detail lebih lanjut, lihat [dokumentasi fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.walk).