Hugging Face's logo

Hub Python Library documentation

API du système de fichiers

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

API du système de fichiers

La classe HfFileSystem fournit une interface de fichiers pythonique vers le Hugging Face Hub basée sur fsspec.

HfFileSystem

HfFileSystem est basé sur fsspec, il est donc compatible avec la plupart des API qu’il propose. Pour plus de détails, consultez notre guide et la référence API de fsspec.

classe huggingface_hub.HfFileSystem

< >

( *args**kwargs )

Paramètres

  • endpoint (str, facultatif) — Endpoint du Hub. Par défaut, https://huggingface.co.
  • 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()). Valeur par défaut : 16. Définissez-le à 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 avoir à appeler manuellement HfFileSystem.invalidate_cache(). Lorsqu'il est activé, l'énumération 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.

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

HfFileSystem offre une compatibilité avec 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, le préfixe de protocole hf:// est facultatif dans les chemins.

Utilisation :

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

>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(token=token)

cp_file

< >

( path1: strpath2: strrevision: str | None = None**kwargs )

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.

Note : Utilisez HfApi.upload_file() lorsque c'est possible pour de meilleures performances.

existe

< >

( path**kwargs ) → bool

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.

Note : Utilisez HfApi.file_exists() lorsque c'est possible pour de meilleures performances.

find

< >

( path: strmaxdepth: int | None = Nonewithdirs: bool = Falsedetail: bool = Falserefresh: bool = Falserevision: str | None = None**kwargs ) → Union[list[str], dict[str, dict[str, Any]]]

Paramètres

  • path (str) — Chemin racine à partir duquel lister les fichiers.
  • maxdepth (int, facultatif) — Profondeur maximale à atteindre dans les sous-répertoires.
  • withdirs (bool, facultatif) — Inclut les chemins des répertoires dans la sortie. Valeur par défaut : False.
  • detail (bool, facultatif) — Si True, renvoie un dictionnaire associant les chemins aux informations de fichier. Valeur par 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 à partir de laquelle 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.

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 un curseur de l’endpoint tree du Hub. Ajustez ce comportement avec l’argument max_workers de HfFileSystem.

get_file

< >

( rpathlpath = Nonecallback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>outfile = None**kwargs )

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, optional) — Optional callback to track download progress. Defaults to no callback.
  • outfile (IO, facultatif) — Objet de type fichier facultatif vers lequel écrire. S'il est fourni, lpath est ignoré.

Copier un fichier distant unique en local.

Note : Lorsque c'est possible, utilisez HfApi.hf_hub_download() ou HfApi.download_bucket_files pour de meilleures performances.

glob

< >

( path: strmaxdepth: int | None = None**kwargs ) → list[str]

Paramètres

  • path (str) — Motif de chemin à correspondre.
  • maxdepth (int, facultatif) — Profondeur maximale à atteindre 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.

info

< >

( path: strrefresh: bool = Falserevision: str | None = None**kwargs ) → dict[str, Any]

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.

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

< >

( path: str | None = None )

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.

isdir

< >

( path ) → bool

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.

isfile

< >

( path ) → bool

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.

ls

< >

( path: strdetail: bool = Truerefresh: bool = Falserevision: str | None = None**kwargs ) → list[Union[str, dict[str, Any]]]

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 à partir de laquelle 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.

Note : Utilisez HfApi.list_repo_tree() lorsque c'est possible pour de meilleures performances.

modifié

< >

( path: str**kwargs ) → datetime

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.

resolve_path

< >

( path: strrevision: str | None = None ) → HfFileSystemResolvedPath

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.

Retourne

HfFileSystemResolvedPath

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

Lève

ValueError ou NotImplementedError

  • ValueError — Si path contient des informations de révision contradictoires.
  • NotImplementedError — Lors de la tentative d’affichage de la liste des dépôts.

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

rm

< >

( path: strrecursive: bool = Falsemaxdepth: int | None = Nonerevision: str | None = None**kwargs )

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.

Note : Utilisez HfApi.delete_file() lorsque c'est possible, pour de meilleures performances.

url

< >

( path: str ) → str

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é.

walk

< >

( path: str*args**kwargs ) → Iterator[tuple[str, list[str], list[str]]]

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.

Update on GitHub

←Client MCP URIs HF→