Hub Python 库文档

文件系统 API

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

文件系统 API

HfFileSystem 类提供了一个基于 fsspec 的 Hugging Face Hub Python 文件接口。

HfFileSystem

HfFileSystem 基于 fsspec,因此与它提供的大多数 API 兼容。有关更多详细信息,请查看我们的指南和 fsspec 的API 参考

class huggingface_hub.HfFileSystem

< >

( *args **kwargs )

参数

访问远程 Hugging Face Hub 仓库,如同访问本地文件系统。

HfFileSystem 提供了 fsspec 兼容性,这对于需要它的库(例如,直接使用 pandas 读取 Hugging Face 数据集)非常有用。但是,由于此兼容层会引入额外的开销。为了获得更好的性能和可靠性,建议尽可能使用 HfApi 方法。

用法

>>> from huggingface_hub import HfFileSystem

>>> fs = HfFileSystem()

>>> # List files
>>> fs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> fs.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 fs.open("my-username/my-model/pytorch_model.bin") as f:
...     data = f.read()
>>> with fs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
...     f.write(data)

__init__

< >

( *args endpoint: typing.Optional[str] = None token: typing.Union[bool, str, NoneType] = None **storage_options )

cp_file

< >

( path1: str path2: str revision: typing.Optional[str] = None **kwargs )

参数

  • path1 (str) — 源路径。
  • path2 (str) — 目标路径。
  • revision (str, 可选) — 要从中复制的 Git 版本。

在仓库内部或仓库之间复制文件。

注意:如果可能,请使用 HfApi.upload_file() 以获得更好的性能。

exists

< >

( path **kwargs ) bool

参数

  • path (str) — 要检查的路径。

返回

布尔值

如果文件存在,则为 True,否则为 False。

检查文件是否存在。

有关更多详细信息,请参阅 fsspec 文档

注意:如果可能,请使用 HfApi.file_exists() 以获得更好的性能。

find

< >

( path: str maxdepth: typing.Optional[int] = None withdirs: bool = False detail: bool = False refresh: bool = False revision: typing.Optional[str] = None **kwargs ) Union[List[str], Dict[str, Dict[str, Any]]]

参数

  • path (str) — 列出文件的根路径。
  • maxdepth (int, 可选) — 深入子目录的最大深度。
  • withdirs (bool, 可选) — 在输出中包含目录路径。默认为 False。
  • detail (bool, 可选) — 如果为 True,则返回一个将路径映射到文件信息的字典。默认为 False。
  • refresh (bool, 可选) — 如果为 True,则绕过缓存并获取最新数据。默认为 False。
  • revision (str, 可选) — 要从中列出的 Git 版本。

返回

Union[List[str], Dict[str, Dict[str, Any]]]

路径列表或文件信息字典。

列出路径下的所有文件。

有关更多详细信息,请参阅 fsspec 文档

get_file

< >

( rpath lpath callback = <fsspec.callbacks.NoOpCallback object at 0x7fd63b7cafb0> outfile = None **kwargs )

参数

  • rpath (str) — 要下载的远程路径。
  • lpath (str) — 要下载到的本地路径。
  • callback (Callback, 可选) — 可选的回调函数,用于跟踪下载进度。默认为无回调。
  • outfile (IO, 可选) — 可选的文件类对象,用于写入。如果提供,lpath 将被忽略。

将单个远程文件复制到本地。

注意:如果可能,请使用 HfApi.hf_hub_download() 以获得更好的性能。

glob

< >

( path **kwargs ) List[str]

参数

  • path (str) — 要匹配的路径模式。

返回

List[str]

匹配模式的路径列表。

通过 glob 匹配查找文件。

有关更多详细信息,请参阅 fsspec 文档

info

< >

( path: str refresh: bool = False revision: typing.Optional[str] = None **kwargs ) Dict[str, Any]

参数

  • path (str) — 要获取信息的路径。
  • refresh (bool, 可选) — 如果为 True,则绕过缓存并获取最新数据。默认为 False。
  • revision (str, 可选) — 要获取信息的 Git 版本。

返回

Dict[str, Any]

包含文件信息(类型、大小、提交信息等)的字典。

获取文件或目录的信息。

有关更多详细信息,请参阅 fsspec 文档

注意:如果可能,请使用 HfApi.get_paths_info()HfApi.repo_info() 以获得更好的性能。

invalidate_cache

< >

( path: typing.Optional[str] = None )

参数

  • path (str, 可选) — 要从缓存中清除的路径。如果未提供,则清除整个缓存。

清除给定路径的缓存。

有关更多详细信息,请参阅 fsspec 文档

isdir

< >

( path ) bool

参数

  • path (str) — 要检查的路径。

返回

布尔值

如果路径是目录,则为 True,否则为 False。

检查路径是否为目录。

有关更多详细信息,请参阅 fsspec 文档

isfile

< >

( path ) bool

参数

  • path (str) — 要检查的路径。

返回

布尔值

如果路径是文件,则为 True,否则为 False。

检查路径是否为文件。

有关更多详细信息,请参阅 fsspec 文档

ls

< >

( path: str detail: bool = True refresh: bool = False revision: typing.Optional[str] = None **kwargs ) List[Union[str, Dict[str, Any]]]

参数

  • 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 文档

注意:如果可能,请使用 HfApi.list_repo_tree() 以获得更好的性能。

modified

< >

( path: str **kwargs ) datetime

参数

  • path (str) — 文件的路径。

返回

datetime

文件的最后提交日期。

获取文件的最后修改时间。

有关更多详细信息,请参阅 fsspec 文档

resolve_path

< >

( path: str revision: typing.Optional[str] = None ) HfFileSystemResolvedPath

参数

  • path (str) — 要解析的路径。
  • revision (str, 可选) — 要解析的仓库版本。默认为路径中指定的版本。

返回

HfFileSystemResolvedPath

已解析的路径信息,包含 repo_typerepo_idrevisionpath_in_repo

引发

ValueErrorNotImplementedError

  • ValueError — 如果路径包含冲突的版本信息。
  • NotImplementedError — 如果尝试列出仓库。

将 Hugging Face 文件系统路径解析为其组件。

rm

< >

( path: str recursive: bool = False maxdepth: typing.Optional[int] = None revision: typing.Optional[str] = None **kwargs )

参数

  • path (str) — 要删除的路径。
  • recursive (bool, 可选) — 如果为 True,则删除目录及其所有内容。默认为 False。
  • maxdepth (int, 可选) — 递归删除时要访问的最大子目录数。
  • revision (str, 可选) — 要从中删除的 git 版本。

从存储库中删除文件。

有关更多详细信息,请参阅 fsspec 文档

注意:如果可能,请使用 HfApi.delete_file() 以获得更好的性能。

url

< >

( 路径: str ) str

参数

  • path (str) — 获取 URL 的路径。

返回

字符串

访问 Hub 上文件或目录的 HTTP URL。

获取给定路径的 HTTP URL。

walk

< >

( 路径: str *args **kwargs ) Iterator[Tuple[str, List[str], List[str]]]

参数

  • 路径 (str) — 列出文件的根路径。

返回

Iterator[Tuple[str, List[str], List[str]]]

一个由(路径、目录名列表、文件名列表)元组组成的迭代器。

返回给定路径下的所有文件。

有关更多详细信息,请参阅 fsspec 文档

< > 在 GitHub 上更新