摘要

根据 PEP 440，发行版可以通过名称和版本，或直接 URL 引用进行识别（参见 PEP440 直接引用）。安装后，名称和版本会记录在项目元数据中，但目前无法获取发行版通过直接 URL 引用识别时使用的 URL 详细信息。

本提案定义了额外的元数据，将由安装前端添加到已安装的发行版中，用于记录直接 URL 来源，供内省已安装软件包数据库的消费者使用（参见 PEP 376）。

动机

本 PEP 的最初动机是允许具有“冻结”操作的工具能够更广泛地重新创建 Python 环境。

具体来说，本 PEP 源于解决 pip 问题 #609 的愿望：即在存在通过直接 URL 引用安装的发行版时改进 pip freeze 的行为。它遵循了 discuss.python.org 上的一个帖子，讨论了实现它的最佳方案。

基本原理

本 PEP 在已安装发行版的 .dist-info 目录中指定了一个新的 direct_url.json 元数据文件。

指定的字段足以重现源存档和 pip 支持的 VCS URL。它们也足以重现 PEP440 直接引用，以及 Pipfile 和 Pipfile.lock 条目。最后，它们足以记录已安装版本的​​分支、标签和/或 Git ref 来源，这些信息由于存在 VCS 检出而已经可用于可编辑安装。

由于已经存在至少三种不同的方式来编码此类信息，本 PEP 使用字典格式，以便不对直接 URL 引用最终必须如何在需求或锁定文件中编码做出任何假设。有关此选择的更多讨论，请参阅下面的替代方案部分。

参考了 Ruby 的 bundler 手册，以验证它是否具有类似的功能，并为本规范中字段的选择和命名提供信息。

JSON 格式允许将来添加额外的字段。

规范

本 PEP 指定在已安装发行版的 .dist-info 目录中创建 direct_url.json 文件，以记录发行版的直接 URL 来源。

此元数据文件的名称和语义的规范来源是《记录已安装发行版的直接 URL 来源》文档。

当安装程序从指定直接 URL 引用（包括 VCS URL）的要求安装发行版时，必须创建此文件。

当从其他类型要求（即名称加版本说明符）安装发行版时，不得创建此文件。

此 JSON 文件必须是一个字典，符合 RFC 8259 并采用 UTF-8 编码。

如果存在，它必须至少包含两个字段。第一个是 url，类型为 string。根据 url 指代的内容，第二个字段必须是 vcs_info（如果 url 是 VCS 引用），archive_info（如果 url 是源存档或 wheel），或 dir_info（如果 url 是本地目录）。这些信息字段的值为一个（可能为空的）子字典，其可能的键定义如下。

url 必须剥离任何敏感的身份验证信息，出于安全原因。

但是，URL 的用户:密码部分可以由环境变量组成，匹配以下正则表达式

\$\{[A-Za-z0-9-_]+\}(:\$\{[A-Za-z0-9-_]+\})?

此外，URL 的用户:密码部分可以是众所周知的、非安全敏感的字符串。一个典型的例子是 git，例如在 ssh://git@gitlab.com 这样的 URL 中。

当 url 指向 VCS 存储库时，必须存在 vcs_info 键，其值为包含以下键的字典

• 必须存在一个 vcs 键（类型 string），包含 VCS 的名称（即 git、hg、bzr、svn 之一）。其他 VCS 应通过编写 PEP 来修订本规范进行注册。url 值必须与相应的 VCS 兼容，以便安装程序可以将其无需转换地传递给 VCS 的 checkout/download 命令。
• 一个 requested_revision 键（类型 string）可能存在，命名要安装的分支/标签/ref/提交/修订版/等（以与 VCS 兼容的格式）。
• 必须存在一个 commit_id 键（类型 string），包含已安装的确切提交/修订号。如果 VCS 支持基于提交哈希的修订标识符，则必须使用此类提交哈希作为 commit_id，以引用已安装源代码的不可变版本。
• 如果安装程序可以发现有关请求修订版的其他信息，则可以添加 resolved_revision 和/或 resolved_revision_type 字段。如果请求的 URL 中未提供修订版，resolved_revision 可以包含已安装的默认分支，并且 resolved_revision_type 将是 branch。如果安装程序确定 requested_revision 是标签，则可以添加 resolved_revision_type，其值为 tag。

当 url 指向源存档或 wheel 时，必须存在 archive_info 键，其值为包含以下键的字典

• 应存在一个 hash 键（类型 string），其值为 <hash-algorithm>=<expected-hash>。建议仅使用标准库 hashlib 模块最新版本无条件提供的哈希算法作为源存档哈希。撰写本文时，该列表包括 'md5'、'sha1'、'sha224'、'sha256'、'sha384' 和 'sha512'。

当 url 指向本地目录时，必须存在 dir_info 键，其值为包含以下键的字典

• editable（类型：boolean）：如果发行版以可编辑模式安装，则为 true，否则为 false。如果省略，默认为 false。

当 url 指向本地目录时，它必须具有 file 方案并符合 RFC 8089。特别是，路径组件必须是绝对路径。将相对路径转换为绝对路径时，应保留符号链接。

顶级 subdirectory 字段可能存在，包含一个目录路径，相对于 VCS 存储库、源存档或本地目录的根目录，用于指定 pyproject.toml 或 setup.py 的位置。

示例

{
    "url": "https://github.com/pypa/pip/archive/1.3.1.zip",
    "archive_info": {
        "hash": "sha256=2dc6b5a470a1bde68946f263f1af1515a2574a150a30d6ce02c6ff742fcc0db8"
    }
}

{
    "url": "https://github.com/pypa/pip.git",
    "vcs_info": {
        "vcs": "git",
        "requested_revision": "1.3.1",
        "resolved_revision_type": "tag",
        "commit_id": "7921be1537eac1e97bc40179a57f0349c2aee67d"
    }
}

{
    "url": "file:///home/user/project",
    "dir_info": {}
}

{
    "url": "file:///home/user/project",
    "dir_info": {
        "editable": true
    }
}

用例

“冻结”环境

诸如 pip freeze 等从已安装 Python 发行版数据库生成需求的工具应在 direct_url.json 存在时加以利用，并优先于版本元数据，以生成更高保真度的输出。在存在 vcs 直接 URL 引用时，应优先使用 commit_id 字段，以提供与原始安装版本最高可能的保真度。如果其需求格式支持，鼓励工具也输出 tag 值（如果存在），因为它具有不可变语义。工具可以根据用户需求选择其他方法。

请注意，本 PEP 的初始迭代并未试图使包含可编辑安装或从本地目录安装的环境可重现，但它试图使它们易于识别。通过本规范的 url 和 dir_info 字段定位本地项目目录，工具可以实现任何适合其用例的策略。

向后兼容性

由于本 PEP 在 .dist-info 目录中指定了一个新文件，因此不存在向后兼容性问题。

备选方案

致谢

许多人帮助使这个 PEP 成为现实。Paul F. Moore 提供了摘要的精髓。Alyssa Coghlan 建议了 direct_url 名称。

版权

本文档置于公共领域或 CC0-1.0-Universal 许可证下，以更宽松者为准。