dvc.api.open()

打开一个被跟踪的文件。

def open(path: str,
         repo: str = None,
         rev: str = None,
         remote: str = None,
         remote_config: dict = None,
         config: dict = None,
         mode: str = "r",
         encoding: str = None)

用法

import dvc.api

with dvc.api.open(
    'get-started/data.xml',
    repo='https://github.com/iterative/dataset-registry'
) as f:
    # ... f is a file-like object that can be processed normally.

描述

打开一个在 DVC 项目中被跟踪的数据或模型文件，并生成相应的文件对象。该文件可以由 DVC（作为输出）或 Git 进行跟踪。

文件对象的具体类型取决于所使用的 mode。更多细节请参考 Python 内置的 open() 函数，该函数在底层被调用。

此函数会直接连接到远程存储，因此可以流式传输文件内容。你的代码可以在数据流式传输时处理缓冲区，从而优化内存使用。

dvc.api.open() 只能作为上下文管理器使用（如示例所示，使用 with 关键字）。

使用 dvc.api.read() 可在一个函数调用中加载完整的文件内容——无需使用上下文管理器。这两个函数均不占用磁盘空间。

参数

path（必需） - 要打开的目标文件的位置和文件名，相对于项目根目录（repo）。
repo — 指定 DVC 项目的所在位置。可以是 URL 或文件系统路径。在线 Git 仓库支持 HTTP 和 SSH 协议（例如 [user@]server:project.git）。默认值：使用当前项目（向上遍历当前工作目录树以查找）。
rev — Git 提交（任何版本，如分支、标签名称、提交哈希或实验名称）。如果 repo 不是 Git 仓库，则忽略此选项。默认值：None（将使用当前工作树）
remote — 用于查找目标数据的DVC 远程存储的名称。默认值：若未提供 remote 参数，则使用 repo 的默认远程存储。对于本地项目，在尝试默认远程之前会先尝试缓存。
remote_config — 传递给 DVC 远程存储的配置选项字典。可用于例如向 remote 提供凭据。
config — 传递给 DVC 项目的配置字典。它将与现有项目配置合并，可用于例如添加一个全新的 remote。
mode — 指定打开文件的模式。默认为 "r"（只读）。与内置函数 open() 中同名参数一致。
encoding — 用于将文件内容解码为字符串的编解码器。仅应在文本模式下使用。默认为 "utf-8"。与内置函数 open() 中同名参数一致。

异常

dvc.exceptions.FileMissingError — repo 中缺少 path 对应的文件。
dvc.exceptions.PathMissingError — 在 repo 中找不到 path。
dvc.exceptions.NoRemoteError — 找不到 remote。

示例：从 DVC 仓库中使用数据或模型

任何在 DVC 项目中被跟踪（并远程存储）的文件都可以通过此 API 直接在 Python 代码中处理。例如，GitHub 上某个公开 DVC 仓库中被跟踪的一个 XML 文件可以这样处理：

from xml.sax import parse
import dvc.api
from mymodule import mySAXHandler

with dvc.api.open(
    'get-started/data.xml',
    repo='https://github.com/iterative/dataset-registry'
) as f:
    parse(f, mySAXHandler)

请注意，我们这里使用了 SAX XML 解析器，因为 dvc.api.open() 能够从远程存储流式读取数据。（在此情况下，mySAXHandler 对象应处理文档的事件驱动解析。）这提升了代码性能（最小化内存使用），通常比将整个数据加载到内存中更快。

如果你只需要将完整文件内容加载到内存中，可以改用 dvc.api.read()：

from xml.dom.minidom import parse
import dvc.api

url = 'https://github.com/iterative/dataset-registry'
xmldata = dvc.api.read('get-started/data.xml', repo=url)
xmldom = parse(xmldata)

示例：访问私有仓库

这只需正确设置 repo 参数即可，例如使用 SSH URL（需要本地已配置好凭据）：

import dvc.api

with dvc.api.open(
    'features.dat',
    repo='git@server.com:path/to/repo.git'
) as f:
    # ... Process 'features'

示例：使用不同版本的数据

通过 rev 参数，你可以指定任意 Git 提交来查找对应产物。这样就可以以编程方式访问任何历史版本或不同的实验结果。例如，假设你的 DVC 仓库对一个 CSV 数据集设置了标签化的发布版本：

import csv
import dvc.api

with dvc.api.open('clean.csv', rev='v1.1.0') as f:
    reader = csv.reader(f)
    # ... Process 'clean' data from version 1.1.0

此外，请注意本示例中我们未提供 repo 参数。DVC 将尝试在当前工作目录树中查找可用的 DVC 项目，并在其本地缓存中查找 clean.csv 的文件内容；如果找到则不会进行下载。更多信息请参见参数部分。

示例：选择特定远程作为数据源

有时我们可能希望指定某个特定的远程存储作为数据源，例如当 repo 没有设置默认远程时。可以通过提供 remote 参数实现：

import dvc.api

with dvc.api.open('activity.log', remote='my-s3-bucket') as f:
    for line in f:
        match = re.search(r'user=(\w+)', line)
        # ... Process users activity log

示例：为远程指定凭据

有关远程配置选项的完整列表，请参见 remote modify。

import dvc.api

remote_config = {
    'access_key_id': 'mykey',
    'secret_access_key': 'mysecretkey',
    'session_token': 'mytoken',
}

with dvc.api.open('data', remote_config=remote_config) as f:
    # ... Process data

示例：更改默认远程并为其指定凭据

有关远程配置选项的完整列表，请参见 remote modify。

import dvc.api

config = {
    'core': {'remote': 'myremote'},
    'remote': {
        'myremote': {
            'access_key_id': 'mykey',
            'secret_access_key': 'mysecretkey',
            'session_token': 'mytoken',
        },
    },
}

with dvc.api.open('data', config=config) as f:
    # ... Process data

示例：指定文本编码

要选择用于打开文本文件的编解码器，请传入一个 encoding 参数：

import dvc.api

with dvc.api.open('data/nlp/words_ru.txt', encoding='koi8_r') as f:
    # ... Process Russian words