# API du système de fichiers

La classe `HfFileSystem` fournit une interface de fichiers pythonique vers le Hugging Face Hub basée sur [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/).

## HfFileSystem[[huggingface_hub.HfFileSystem]]

`HfFileSystem` est basé sur [fsspec](https://filesystem-spec.readthedocs.io/en/latest/), il est donc compatible avec la plupart des API qu’il propose. Pour plus de détails, consultez [notre guide](../guides/hf_file_system) et la [référence API](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem) de fsspec.

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

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

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

**Paramètres :**

endpoint (`str`, *facultatif*) : Point de terminaison du Hub. Valeur par défaut : .

token (`bool` ou `str`, *facultatif*) : Un jeton d'accès utilisateur valide (chaîne de caractères). Par défaut, le jeton enregistré localement est utilisé, ce qui est la méthode recommandée pour l'authentification (voir https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Pour désactiver l'authentification, passez `False`.

block_size (`int`, *facultatif*) : Taille du bloc pour la lecture et l'écriture des fichiers.

expand_info (`bool`, *facultatif*) : Indique s'il faut étendre les informations des fichiers.

max_workers (`int`, *facultatif*) : Nombre maximal de requêtes concurrentes utilisées pour lister de grands répertoires en parallèle (voir [find()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_file_system#huggingface_hub.HfFileSystem.find)). La valeur par défaut est 16. Définissez-la à 1 pour désactiver les listings parallèles.

live_follow (`bool`, *facultatif*) : Indique s'il faut suivre les modifications des fichiers dans les buckets au fur et à mesure qu'elles se produisent sur le Hub, afin que les listes mises en cache restent à jour sans appels manuels de [HfFileSystem.invalidate_cache()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_file_system#huggingface_hub.HfFileSystem.invalidate_cache). Lorsqu'activé, la liste d'un bucket ouvre une connexion en arrière-plan vers le flux d'événements du Hub pour ce bucket. N'a aucun effet sur les dépôts de modèles, de jeux de données et d'espaces (le Hub ne diffuse pas les modifications pour ceux-ci).

- ****storage_options** (`dict`, *facultatif*) : Options supplémentaires pour le système de fichiers. Voir la [documentation de fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.__init__).

Accédez à un dépôt distant du Hugging Face Hub comme s’il s’agissait d’un système de fichiers local.

> [!WARNING]
> [HfFileSystem](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_file_system#huggingface_hub.HfFileSystem) offre une compatibilité fsspec, ce qui est utile pour les bibliothèques qui en ont besoin (par exemple, la lecture directe des jeux de données Hugging Face avec `pandas`). Cependant, cette couche de compatibilité introduit un surcoût supplémentaire. Pour de meilleures performances et une meilleure fiabilité, il est recommandé d’utiliser les méthodes de `HfApi` lorsque c’est possible.

Le système de fichiers prend en charge les chemins pour le protocole `hf://`, qui suit les schémas d’URL suivants :

* Dépôts de modèles, de jeux de données et d'espaces :

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

* Buckets (stockage générique) :

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

Note : lors de l'utilisation directe de [HfFileSystem](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_file_system#huggingface_hub.HfFileSystem), le préfixe de protocole `hf://` est facultatif dans les chemins.

Utilisation :

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

Spécifiez un jeton pour l’authentification :
```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)
```

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

**Paramètres :**

path1 (`str`) : Chemin source à copier.

path2 (`str`) : Chemin de destination vers lequel copier.

revision (`str`, *facultatif*) : La révision git à copier.

Copier un fichier au sein d’un dépôt, entre dépôts, ou vers un bucket.

> [!WARNING]
> Note : Utilisez `HfApi.upload_file()` lorsque c'est possible pour de meilleures performances.

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

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

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

**Paramètres :**

path (`str`) : Chemin à vérifier.

**Retourne :** `bool`

Vrai si le fichier existe, Faux sinon.

Vérifier si un fichier existe.

Pour plus de détails, consultez la [documentation de fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.exists).

> [!WARNING]
> Note : Utilisez `HfApi.file_exists()` lorsque c'est possible pour de meilleures performances.

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

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

**Paramètres :**

path (`str`) : Chemin racine à partir duquel lister les fichiers.

maxdepth (`int`, *facultatif*) : Profondeur maximale à descendre dans les sous-répertoires.

withdirs (`bool`, *facultatif*) : Inclure les chemins de répertoire dans la sortie. Valeur par défaut : False.

detail (`bool`, *facultatif*) : Si True, renvoie un dictionnaire associant les chemins aux informations de fichier. Défaut : False.

refresh (`bool`, *facultatif*) : Si True, contourne le cache et récupère les données les plus récentes. Valeur par défaut : False.

revision (`str`, *facultatif*) : La révision git à lister.

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

Liste de chemins ou dictionnaire d’informations de fichiers.

Liste tous les fichiers situés sous le chemin.

Pour plus de détails, consultez la [documentation de fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.find).

> [!TIP]
> Les dépôts volumineux sont répertoriés répertoire par répertoire, en parallèle, afin de contourner la pagination basée sur les curseurs de l’endpoint `tree` du Hub. Ajustez ce comportement avec l’argument `max_workers` de [HfFileSystem](/docs/huggingface_hub/v2.4.0/fr/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)
```

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

**Paramètres :**

rpath (`str`) : Chemin distant à partir duquel effectuer le téléchargement.

lpath (`str`, *facultatif*) : Chemin local de téléchargement. Peut être omis si `outfile` est fourni.

callback (`Callback`, *facultatif*) : `Callback` facultatif pour suivre la progression du téléchargement. Par défaut, aucun callback n'est utilisé.

outfile (`IO`, *facultatif*) : Objet de type fichier facultatif à écrire. S'il est fourni, `lpath` est ignoré.

Copier un fichier distant unique en local.

> [!WARNING]
> Note : Lorsque c'est possible, utilisez `HfApi.hf_hub_download()` ou `HfApi.download_bucket_files` pour de meilleures performances.

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

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

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

**Paramètres :**

path (`str`) : Motif de chemin à correspondre.

maxdepth (`int`, *facultatif*) : Profondeur maximale à descendre dans les répertoires. Par défaut, aucune limite.

**Retourne :** `list[str]`

Liste des chemins correspondant au motif.

Trouver des fichiers par correspondance de glob.

Pour plus de détails, consultez la [documentation de 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)
```

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

**Paramètres :**

path (`str`) : Chemin pour lequel obtenir des informations.

refresh (`bool`, *facultatif*) : Si True, contourne le cache et récupère les données les plus récentes. Valeur par défaut : False.

revision (`str`, *facultatif*) : La révision git à partir de laquelle obtenir les informations.

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

Dictionnaire contenant les informations sur le fichier (type, taille, informations de commit, etc.).

Obtenir des informations sur un fichier ou un répertoire.

Pour plus de détails, consultez la [documentation de fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.info).

> [!WARNING]
> Note : Lorsque c'est possible, utilisez `HfApi.get_paths_info()` ou `HfApi.repo_info()` pour de meilleures performances (ou `HfApi.get_bucket_paths_info()` ou `HfApi.bucket_info()` pour les buckets)

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

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

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

**Paramètres :**

path (`str`, *facultatif*) : Chemin à purger du cache. S'il n'est pas fourni, l'intégralité du cache est purgée.

Effacer le cache pour un chemin donné.

Pour plus de détails, consultez la [documentation de fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.invalidate_cache).

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

```python
isdir(path)
```

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

**Paramètres :**

path (`str`) : Chemin à vérifier.

**Retourne :** `bool`

Vrai si path est un répertoire, Faux sinon.

Vérifie si un chemin est un répertoire.

Pour plus de détails, consultez la [documentation de fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.isdir).

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

```python
isfile(path)
```

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

**Paramètres :**

path (`str`) : Chemin à vérifier.

**Retourne :** `bool`

Vrai si path est un fichier, Faux sinon.

Vérifier si un chemin est un fichier.

Pour plus de détails, consultez la [documentation de 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)
```

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

**Paramètres :**

path (`str`) : Chemin vers le répertoire.

detail (`bool`, *facultatif*) : Si True, renvoie une liste de dictionnaires contenant des informations sur les fichiers. Si False, renvoie une liste de chemins de fichiers. Valeur par défaut : True.

refresh (`bool`, *facultatif*) : Si True, contourne le cache et récupère les données les plus récentes. Valeur par défaut : False.

revision (`str`, *facultatif*) : La révision git à lister.

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

Liste de chemins de fichiers (si detail=False) ou liste de dictionnaires d'informations sur les fichiers (si detail=True).

Lister le contenu d'un répertoire.

Pour plus de détails, consultez la [documentation de fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.ls).

> [!WARNING]
> Note : Utilisez `HfApi.list_repo_tree()` lorsque c'est possible pour de meilleures performances.

#### modifié[[huggingface_hub.HfFileSystem.modified]]

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

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

**Paramètres :**

path (`str`) : Chemin vers le fichier.

**Retourne :** `datetime`

Date et heure de dernière modification du fichier.

Obtenir l'heure de dernière modification d'un fichier.

Pour plus de détails, consultez la [documentation de 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)
```

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

**Paramètres :**

path (`str`) : Chemin à résoudre.

revision (`str`, *facultatif*) : La révision du dépôt à résoudre. Par défaut, la révision spécifiée dans le chemin est utilisée.

**Retourne :** `HfFileSystemResolvedPath`

Informations sur le chemin résolu contenant `repo_type`, `repo_id`, `revision` et `path_in_repo`.

**Exceptions levées :** ``ValueError`` ou ``NotImplementedError``

- ``ValueError`` -- Si path contient des informations de révision contradictoires.
- ``NotImplementedError`` -- Si vous essayez de lister des dépôts.

Résoudre un chemin de système de fichiers Hugging Face en ses composants.

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

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

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

**Paramètres :**

path (`str`) : Chemin à supprimer.

recursive (`bool`, *facultatif*) : Si True, supprime le répertoire et tout son contenu. Valeur par défaut : False.

maxdepth (`int`, *facultatif*) : Nombre maximal de sous-répertoires à parcourir lors d'une suppression récursive.

revision (`str`, *facultatif*) : La révision git à partir de laquelle supprimer.

Supprimer des fichiers d'un dépôt.

Pour plus de détails, consultez la [documentation de fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.rm).

> [!WARNING]
> Note : Utilisez `HfApi.delete_file()` lorsque c'est possible, pour de meilleures performances.

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

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

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

**Paramètres :**

path (`str`) : Chemin pour lequel obtenir l'URL.

**Retourne :** `str`

URL HTTP pour accéder au fichier ou au répertoire sur le Hub.

Obtenir l'URL HTTP du chemin donné.

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

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

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

**Paramètres :**

path (`str`) : Chemin racine à partir duquel lister les fichiers.

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

Un itérateur de tuples (chemin, liste de noms de répertoires, liste de noms de fichiers).

Retourne tous les fichiers situés sous le chemin donné.

Pour plus de détails, consultez la [documentation de fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.walk).