安装程序和库中 provenance_url.json 的存在

对 Python 生态系统中现有安装程序、库和依赖管理器进行了全面调查，分析了为每个工具添加 provenance_url.json 支持的影响。总而言之，截至撰写本 PEP 时，未发现重大的向后兼容性问题、冲突或可行性障碍。有关调查的更多详细信息，请参阅 附录：安装程序和库调查 部分。

与 direct_url.json 的兼容性

本提案未对 PEP 610 及其 相应规范 PyPA 规范 中描述的 direct_url.json 文件进行任何更改。

provenance_url.json 文件的内容设计旨在最终允许安装程序在直接 URL 指向源存档或 wheel 时重用支持 direct_url.json 的一些逻辑。

provenance_url.json 和 direct_url.json 文件之间的主要区别在于 provenance_url.json 文件中强制性的键及其值。这有助于确保 provenance_url.json 文件的使用者可以在文件存在于 .dist-info 目录中时依赖其内容。

有效 provenance_url.json 的示例

一个有效的 provenance_url.json 列出了多个哈希

{
  "archive_info": {
    "hashes": {
      "blake2s": "fffeaf3d0bd71dc960ca2113af890a2f2198f2466f8cd58ce4b77c1fc54601ff",
      "sha256": "236bcb61156d76c4b8a05821b988c7b8c35bf0da28a4b614e8d6ab5212c25c6f",
      "sha3_256": "c856930e0f707266d30e5b48c667a843d45e79bb30473c464e92dfa158285eab",
      "sha512": "6bad5536c30a0b2d5905318a1592948929fbac9baf3bcf2e7faeaf90f445f82bc2b656d0a89070d8a6a9395761f4793c83187bd640c64b2656a112b5be41f73d"
    }
  },
  "url": "https://files.pythonhosted.org/packages/07/51/2c0959c5adf988c44d9e1e0d940f5b074516ecc87e96b1af25f59de9ba38/pip-23.0.1-py3-none-any.whl"
}

一个有效的 provenance_url.json 列出了单个哈希条目

{
  "archive_info": {
    "hashes": {
      "sha256": "236bcb61156d76c4b8a05821b988c7b8c35bf0da28a4b614e8d6ab5212c25c6f"
    }
  },
  "url": "https://files.pythonhosted.org/packages/07/51/2c0959c5adf988c44d9e1e0d940f5b074516ecc87e96b1af25f59de9ba38/pip-23.0.1-py3-none-any.whl"
}

一个有效的 provenance_url.json 列出了用于构建和安装 wheel 的源分发

{
  "archive_info": {
    "hashes": {
      "sha256": "8bfe29f17c10e2f2e619de8033a07a224058d96b3bfe2ed61777596f7ffd7fa9"
    }
  },
  "url": "https://files.pythonhosted.org/packages/1d/43/ad8ae671de795ec2eafd86515ef9842ab68455009d864c058d0c3dcf680d/micropipenv-0.0.1.tar.gz"
}

无效 provenance_url.json 的示例

以下示例在 archive_info 字典中包含一个 hash 键，这最初是在 记录已安装分发版的直接 URL 来源 中记录的数据结构中设计的。为避免与 hashes 产生任何可能的混淆以及保持哈希值同步所需的额外检查，不得出现 hash 键。

{
  "archive_info": {
    "hash": "sha256=236bcb61156d76c4b8a05821b988c7b8c35bf0da28a4b614e8d6ab5212c25c6f",
    "hashes": {
      "sha256": "236bcb61156d76c4b8a05821b988c7b8c35bf0da28a4b614e8d6ab5212c25c6f"
    }
  },
  "url": "https://files.pythonhosted.org/packages/07/51/2c0959c5adf988c44d9e1e0d940f5b074516ecc87e96b1af25f59de9ba38/pip-23.0.1-py3-none-any.whl"
}

另一个例子展示了一个无效的哈希名称。引用的哈希名称与本 PEP 和 Python 文档中 hashlib.hash.name 下描述的规范哈希名称不符。

{
  "archive_info": {
    "hashes": {
      "SHA-256": "236bcb61156d76c4b8a05821b988c7b8c35bf0da28a4b614e8d6ab5212c25c6f"
    }
  },
  "url": "https://files.pythonhosted.org/packages/07/51/2c0959c5adf988c44d9e1e0d940f5b074516ecc87e96b1af25f59de9ba38/pip-23.0.1-py3-none-any.whl"
}

最后一个例子展示了一个 provenance_url.json 文件，其中下载的工件没有可用的哈希

{
  "archive_info": {
    "hashes": {}
   }
  "url": "https://files.pythonhosted.org/packages/07/51/2c0959c5adf988c44d9e1e0d940f5b074516ecc87e96b1af25f59de9ba38/pip-23.0.1-py3-none-any.whl"
}

pip 命令及其对 provenance_url.json 和 direct_url.json 的影响示例

这些命令生成 direct_url.json 文件，但不生成 provenance_url.json 文件。这些示例遵循 直接 URL 数据结构 规范中的示例

• pip install https://example.com/app-1.0.tgz
• pip install https://example.com/app-1.0.whl
• pip install "git+https://example.com/repo/app.git#egg=app&subdirectory=setup"
• pip install ./app
• pip install file:///home/user/app
• pip install --editable "git+https://example.com/repo/app.git#egg=app&subdirectory=setup"（在这种情况下，url 将是 git 仓库被克隆到的本地目录，并且 dir_info 将存在并带有 "editable": true 且未设置 vcs_info）
• pip install -e ./app

生成 provenance_url.json 文件但不生成 direct_url.json 文件的命令

• pip install app
• pip install app~=2.2.0
• pip install app --no-index --find-links "https://example.com/"

此行为可以使用 PR pypa/pip#11865 中对 pip 的更改进行测试。

将文件命名为 direct_url.json 而不是 provenance_url.json

为了保持与 记录已安装分发版的直接 URL 来源 的向后兼容性，该文件不能命名为 direct_url.json，根据该规范的文本

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

这种更改可能会对 direct_url.json 的使用者引入向后兼容性问题，这些使用者仅在通过直接 URL 引用安装分发时才依赖其存在。

弃用 direct_url.json 并仅使用 provenance_url.json

文件 direct_url.json 已经通过 直接 URL 数据结构 规范确立，并已被安装程序使用。例如，pip 使用 direct_url.json 在 pip freeze 上报告直接 URL 引用。弃用 direct_url.json 将需要对 pip 中 pip freeze 的实现进行额外更改（参见 PR fridex/pip#2），并且可能对已有的 direct_url.json 消费者引入向后兼容性问题。

将哈希键保留在 archive_info 字典中

直接 URL 数据结构 规范讨论了在 archive_info 字典中包含 hash 键和 hashes 键的可能性。本 PEP 明确不将 hash 键包含在 provenance_url.json 文件中，并且只允许 hashes 键存在。通过这样做，我们消除了文件中的可能冗余、可能的混淆以及为确保哈希同步而需要进行的任何额外检查。

允许不声明哈希

对于从 pip 缓存安装 wheel 文件并使用旧版本 pip 构建的情况，pip 不会记录下载的源分发版的哈希。由于我们没有这些下载的源分发版的哈希，provenance_url.json 文件中的 hashes 键将不包含任何条目。在这种情况下，由于来源信息不完整，pip 不会创建任何 provenance_url.json 文件。建议消费者在这些情况下使用更新版本的 pip 重新构建 wheel。

uv 的开发者 提出了对 provenance_url.json 文件中要求至少一个哈希的担忧，因为 uv 除非明确要求，否则不计算分发哈希。然而，要求至少一个哈希有助于对分发进行完整性检查。这在涉及锁文件或将分发标识为 SBOM 的一部分的场景中很重要。provenance_url.json 文件强制包含下载分发的至少一个哈希。作为安装过程的一部分不计算分发哈希的安装程序（例如，出于性能原因）可以省略创建 provenance_url.json 文件。

使哈希键可选

PEP 610 及其 相应规范 PyPA 规范 建议在 direct_url.json 文件中的 archive_info 中包含 hashes 键，但这不是必需的（根据 RFC 2119 语言）

应该存在一个哈希键，其值为一个字典，将哈希名称映射到文件的十六进制编码摘要。

本 PEP 要求，如果创建 provenance_url.json 文件，则 archive_info 中必须包含 hashes 键；根据本 PEP

archive_info 的值必须是一个字典，其中包含一个键 hashes。

通过这样做，provenance_url.json 的消费者可以在安装程序创建 provenance_url.json 文件时检查工件摘要。

存储索引 URL

曾提出一种可能性，将索引 URL 作为文件内容的一部分存储。此索引 URL 将表示 pip 配置中配置的索引，或使用 --index-url 或 --extra-index-url 选项指定的索引。存储此信息被认为会引起混淆，尤其是在使用其他安装选项（如 --find-links）时。由于实际的索引 URL 与下载 wheel 文件的位置并非严格绑定，我们决定不在 provenance_url.json 文件中存储索引 URL。

Conda 中 provenance_url.json 文件的可用性

我们希望从 Conda 维护者那里获得关于 provenance_url.json 文件的反馈。目前尚不清楚 Conda 是否愿意采用 provenance_url.json 文件。Conda 已经将来源相关信息（类似于本 PEP 中提议的来源信息）存储在 conda-meta 目录中的 JSON 文件中，遵循其安装过程中的操作。

在下游安装程序中使用 provenance_url.json

提议的 provenance_url.json 文件主要旨在由 Python 安装程序采用。其他安装程序，如 APT 或 DNF，可能会以其自身特定于下游包管理的方式记录已安装的下游 Python 分发包的来源。预计这些下游包安装程序不会创建提议的文件，因此它们被有意地排除在本 PEP 之外。然而，这些安装程序的开发人员或维护者的任何输入对于可能丰富 provenance_url.json 文件并以某种方式提供帮助都很有价值。

pip

pip 内部 API 中负责安装 wheel 的函数，名为 _install_wheel，不会在 .dist-info 目录中存储任何 provenance_url.json 文件。此外，在 pypa/pip#11865 中向 pip 引入上述文件的原型演示了在 pip 源代码中整合处理 provenance_url.json 文件的逻辑。

由于 pip 被下面提到的一些工具用于安装 Python 包分发，因此 pip 的发现适用于这些工具，因为 pip 不允许在其内部 API 中参数化在 .dist-info 目录中创建文件。下面提到的大多数使用 pip 的工具都将 pip 作为子进程调用，这不会对 provenance_url.json 文件最终是否存在于 .dist-info 目录中产生影响。

distlib

distlib 实现了操纵 dist-info 目录的低级功能。根据 distlib 的源代码，已安装分发数据库不使用任何名为 provenance_url.json 的文件。

Pipenv

Pipenv 使用 pip 来安装 Python 包分发。没有发现任何额外的逻辑会导致在 .dist-info 目录中引入 provenance_url.json 文件时出现向后兼容性问题。

installer

installer 不显式创建 provenance_url.json 文件。然而，根据 记录已安装项目 规范，installer 允许传递 additional_metadata 参数以在 .dist-info 目录中创建文件 - 请参阅 源代码。为避免任何向后兼容性问题，任何使用 installer 的库或工具不得使用上述 additional_metadata 参数请求创建 provenance_url.json 文件。

Poetry

Poetry 中的安装逻辑取决于 installer.modern-installer 配置选项（参见文档）。

在 installer.modern-installer 配置选项设置为 false 的情况下，Poetry 使用 pip 来安装 Python 包分发。

另一方面，当 installer.modern-installer 配置选项设置为 true 时，Poetry 使用 安装程序来安装 Python 包分发。从链接的源可以看出，没有传递任何名为 provenance_url.json 的额外元数据文件，这会导致与本 PEP 的兼容性问题。

Conda

Conda 在安装 Python 包分发时不会创建任何 provenance_url.json 文件。

Hatch

Hatch 使用 pip 来安装项目依赖项。

micropipenv

由于 micropipenv 是 pip 的一个封装，它使用 pip 来安装 Python 分发，既用于 锁文件，也用于 需求文件。

Thamos

Thamos 使用 micropipenv 来安装 Python 包分发，因此 micropipenv 的任何发现都适用于 Thamos。

PDM

PDM 使用安装程序 安装二进制分发版。它最终在 .dist-info 目录中创建的唯一附加元数据文件是 REFER_TO 文件。

uv

uv 用 Rust 编写，并在安装 wheels 时使用其自己的安装逻辑。它不会在 .dist-info 目录中创建任何与 provenance_url.json 文件命名冲突的附加文件。