文件系统 API

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

HfFileSystem

HfFileSystem 基于 fsspec，因此它与 fsspec 提供的绝大多数 API 兼容。欲了解更多详情，请查看我们的指南和 fsspec 的 API 参考。

class huggingface_hub.HfFileSystem

< 源代码 >

( *args **kwargs )

参数

token (`str` 或 `bool`, *可选*) — 有效的用户访问令牌 (字符串)。默认为本地保存的令牌，这是推荐的身份验证方法 (参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证，请传递 False。
endpoint (`str`, *可选*) — Hub 的端点。默认为 https://huggingface.co。

访问远程 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`) — 要检查的路径。

返回值

bool

如果文件存在，则为 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, optional) — 要从中列出的 git 修订版本（可选）。

返回值

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

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

列出路径下的所有文件。

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

get_file

< source >

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

参数

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

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

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

glob

< source >

( path: str **kwargs ) → List[str]

参数

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

返回值

List[str]

与模式匹配的路径列表。

通过 glob 匹配查找文件。

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

info

< source >

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

参数

path (str) — 获取信息的路径。
refresh (bool, optional) — 如果为 True，则绕过缓存并获取最新数据。默认为 False。
revision (str, optional) — 要从中获取信息的 git 修订版本（可选）。

返回值

Dict[str, Any]

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

获取有关文件或目录的信息。

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

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

invalidate_cache

< source >

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

参数

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

清除给定路径的缓存。

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

isdir

< source >

( path ) → bool

参数

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

返回值

bool

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

检查路径是否为目录。

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

isfile

< source >

( path ) → bool

参数

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

返回值

bool

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

检查路径是否为文件。

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

ls

< source >

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

参数

path (str) — 目录的路径。
detail (bool, optional) — 如果为 True，则返回包含文件信息字典的列表。如果为 False，则返回文件路径列表。默认为 True。
refresh (bool, optional) — 如果为 True，则绕过缓存并获取最新数据。默认为 False。
revision (str, optional) — 要从中列出的 git 修订版本（可选）。

返回值

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

文件路径列表（如果 detail=False）或文件信息字典列表（如果 detail=True）。

列出目录的内容。

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

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

modified

< source >

( path: str **kwargs ) → datetime

参数

path (str) — 文件路径。

返回值

datetime

文件的最后提交日期。

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

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

resolve_path

< source >

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

参数

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

返回值

HfFileSystemResolvedPath

包含 repo_type、repo_id、revision 和 path_in_repo 的已解析路径信息。

Raises

ValueError 或 NotImplementedError

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

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

rm

< source >

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

参数

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

从仓库中删除文件。

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

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

url

< source >

( path: str ) → str

参数

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

返回值

str

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

获取给定路径的 HTTP URL。

walk

< source >

( path: str *args **kwargs ) → Iterator[Tuple[str, List[str], List[str]]]

参数

path (str) — 从根路径列出文件。

返回值

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

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

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

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

< > 在 GitHub 上更新

Hub Python 库

文件系统 API

HfFileSystem

class huggingface_hub.HfFileSystem

__init__

cp_file

exists

find

get_file

glob

info

invalidate_cache

isdir

isfile

ls

modified

resolve_path

rm

url

walk

init