DVCFileSystem

DVCFileSystem 为 DVC 仓库提供了一个 Python 风格的文件接口（与 fsspec 兼容）。它是一个只读文件系统，因此不支持任何写入操作，例如 put_file、cp、rm、mv、mkdir 等。

class DVCFileSystem(AbstractFileSystem):
    def __init__(
        self,
        repo: Optional[str] = None,
        rev: Optional[str] = None,
        config: Optional[Dict[str, Any]] = None,
        **kwargs,
    ):

DVCFileSystem 提供了对仓库中所有文件/目录的统一视图，无论是由 Git 跟踪、DVC 跟踪，还是未跟踪的文件（对于本地仓库而言）。它可以复用 DVC 缓存中的文件，也可以从支持的远程存储流式读取数据。

>>> from dvc.api import DVCFileSystem
# opening a local repository
>>> fs = DVCFileSystem("/path/to/local/repository")
# opening a remote repository
>>> repo = "https://github.com/iterative/example-get-started.git"
>>> fs = DVCFileSystem(repo, rev="main")

参数

repo - 可选的 DVC 项目 URL 或本地路径。如果未指定，则使用当前工作目录下的 DVC 项目。（等同于 dvc.api.open() 和 dvc.api.read() 中的 repo 参数）

该参数在 dvc>=3.60 版本中从 url 重命名为 repo。如果你使用的是较早版本并以关键字方式传参，请将 url 替换为 repo。
rev - 可选的 Git 提交（任何版本，例如分支或标签名、提交哈希，或实验名称）。
config - 可选的配置字典，传递给 DVC 项目。

打开文件

>>> with fs.open("model.pkl") as f:
        model = pickle.load(f)

这类似于 dvc.api.open()，返回一个类文件对象。注意，与 dvc.api.open() 不同的是，mode 默认为二进制模式，即 "rb"。如果使用文本模式（"r"），还可以指定 encoding 参数。

读取文件

>>> text = fs.read_text("get-started/data.xml", encoding="utf-8")

这类似于 dvc.api.read()，它将文件内容作为字符串返回。

要获取文件的二进制内容，可以使用 read_bytes() 或 cat_file()。

>>> contents = fs.read_bytes("get-started/data.xml")

递归列出所有 DVC 跟踪的文件

>>> fs.find("/", detail=False, dvc_only=True)
[
    '/data/data.xml',
    '/data/features/test.pkl',
    '/data/features/train.pkl',
    '/data/prepared/test.tsv',
    '/data/prepared/train.tsv',
    '/evaluation/importance.png',
    '/model.pkl'
]

这类似于 dvc ls --recursive --dvc-only CLI 命令。注意，"/" 被视为 Git 仓库的根目录。你可以指定子路径，仅返回该目录下的条目。类似地，还有非递归的 fs.ls() 方法。

列出所有文件（包括 Git 跟踪的文件）

>>> fs.find("/", detail=False)
[
    ...
    '/.gitignore',
    '/README.md',
    '/data/.gitignore',
    '/data/data.xml',
    '/data/features/test.pkl',
    '/data/features/train.pkl',
    '/data/prepared/test.tsv',
    '/data/prepared/train.tsv',
    ...
    '/evaluation/.gitignore',
    '/evaluation/importance.png',
    '/evaluation/plots/confusion_matrix.json',
    '/evaluation/plots/precision_recall.json',
    '/evaluation/plots/roc.json',
    '/model.pkl',
    ...
]

这类似于 dvc ls --recursive CLI 命令。它返回所有由 DVC 和 Git 跟踪的文件，如果文件系统是在本地打开的，还包括本地未跟踪的文件。

下载文件或目录

>>> fs.get_file("data/data.xml", "data.xml")

这会将 "data/data.xml" 文件下载到当前工作目录，并保存为 "data.xml"。DVC 跟踪的文件如果存在于缓存中则从缓存下载，否则会从远程存储流式获取。

>>> fs.get("data", "data", recursive=True)

这会将 "data" 目录中的所有文件（无论是 Git 跟踪还是 DVC 跟踪）下载到本地的 "data" 目录中。同样，如果文件不存在于缓存中，DVC 可能会从远程获取这些文件。

使用子仓库

如果你在 Git 仓库的子目录中初始化了 DVC，请使用 DVCFileSystem(repo, subrepos=True) 来访问该子目录。

>>> from dvc.api import DVCFileSystem
>>> repo = "https://github.com/iterative/monorepo-example.git"
# by default, DVC initialized in a subdirectory will be ignored
>>> fs = DVCFileSystem(repo, rev="develop")
>>> fs.find("nlp", detail=False, dvc_only=True)
[]
# use subrepos=True to list those files
>>> fs = DVCFileSystem(repo, subrepos=True, rev="develop")
>>> fs.find("nlp", detail=False, dvc_only=True)
['nlp/data/data.xml', 'nlp/data/features/test.pkl', 'nlp/data/features/train.pkl', 'nlp/data/prepared/test.tsv', 'nlp/data/prepared/train.tsv', 'nlp/eval/importance.png', 'nlp/model.pkl']

fsspec API 参考

由于 DVCFileSystem 基于fsspec，因此它与 fsspec 提供的大多数 API 兼容。当 DVC 与任何其他兼容 fsspec 的库（例如 Hugging Face Datasets）安装在同一 Python 环境中时，只要在调用 fsspec 函数时提供了 dvc:// 文件系统 URL，就会自动使用 DVCFileSystem。更多详情请参阅 fsspec 的API 参考。

请注意，dvc:// URL 包含的是你希望加载的文件相对于 DVC 项目根目录的路径。dvc:// URL 不应包含 Git 仓库的 URL。Git 仓库 URL 应通过 DVCFileSystem 的 repo 参数单独提供。

使用 dvc:// URL 时，DVCFileSystem 的额外构造参数（如 repo 或 rev）应根据所调用的具体 fsspec 方法，通过 storage_options 字典或作为关键字参数传入。具体细节请参考 fsspec 文档。

fsspec API 示例：

对于将文件系统参数作为额外关键字参数的方法：

>>> import fsspec
>>> fsspec.open(
...   "dvc://workshop/satellite-data/jan_train.csv",
...   repo="https://github.com/iterative/dataset-registry.git",
... )
<OpenFile 'workshop/satellite-data/jan_train.csv'>

对于通过 storage_options 字典传递文件系统参数的方法：

>>> import fsspec
>>> fsspec.get_fs_token_paths(
...   "dvc://workshop/satellite-data/jan_train.csv",
...   storage_options={"repo": "https://github.com/iterative/dataset-registry.git"},
... )
(<dvc.fs.dvc._DVCFileSystem object at 0x113f7a290>, '06e54af48d3513bf33a8988c47e6fb47', ['workshop/satellite-data/jan_train.csv'])