摘要

根据 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 条目。最后，它们足以记录已安装版本的、通过 VCS 检出存在而已可用的分支、标签和/或 Git ref 来源。

由于至少已经存在三种不同的方法来编码此类信息，因此此 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是源代码归档文件或轮子）或dir_info（如果url是本地目录）。这些信息字段的值为（可能为空的）子字典，其中包含下面定义的可能键。

url**必须**出于安全原因删除任何敏感的身份验证信息。

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

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

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

当url引用 VCS 存储库时，vcs_info键**必须**作为字典存在，其中包含以下键

• **必须**存在vcs键（类型为string），其中包含 VCS 的名称（即git、hg、bzr、svn之一）。其他 VCS **应该**通过编写 PEP 来修改此规范进行注册。url值**必须**与相应的 VCS 兼容，以便安装程序可以将其在不进行转换的情况下传递给 VCS 的检出/下载命令。
• requested_revision键（类型为string）**可以**存在，用于命名要安装的分支/标签/引用/提交/修订版等（以与 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引用源代码归档文件或轮子时，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 许可证，以较宽松者为准。