安装程序和库中 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 键，如 Recording the Direct URL Origin of installed distributions 中记录的数据结构最初设计的那样。**不得**存在 hash 键，以防止与 hashes 发生任何可能的混淆，以及为保持哈希值同步而需要进行的其他检查。

{
  "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 文件。这些示例遵循 Direct 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 来源](https://packaging.pythonlang.cn/en/latest/specifications/direct-url/#direct-url) 的向后兼容性，根据该规范的文本，文件不能命名为 `direct_url.json`。

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

此类更改可能会导致 `direct_url.json` 的使用者出现向后兼容性问题，因为他们仅在使用直接 URL 引用安装发行版时才依赖于其存在。

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

文件 `direct_url.json` 已由 [直接 URL 数据结构](https://packaging.pythonlang.cn/en/latest/specifications/direct-url-data-structure/#direct-url-data-structure) 规范很好地建立，并且已被安装程序使用。例如，`pip` 使用 `direct_url.json` 在 `pip freeze` 中报告直接 URL 引用。弃用 `direct_url.json` 将需要对 pip 中的 `pip freeze` 实现进行其他更改（参见 PR [fridex/pip#2](https://github.com/fridex/pip/pull/2)），并可能导致已有的 `direct_url.json` 使用者出现向后兼容性问题。

在 archive_info 字典中保留哈希键

[直接 URL 数据结构](https://packaging.pythonlang.cn/en/latest/specifications/direct-url-data-structure/#direct-url-data-structure) 规范讨论了在 `archive_info` 字典中包含 `hash` 键以及 `hashes` 键的可能性。本 PEP 明确地**不**在 `provenance_url.json` 文件中包含 `hash` 键，并且仅允许 `hashes` 键存在。通过这样做，我们消除了文件中可能的冗余、可能的混淆以及需要执行的任何其他检查以确保哈希值同步。

允许不声明哈希值

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

使 hashes 键可选

[PEP 610](../pep-0610/) 和 [其相应的规范 PyPA 规范](https://packaging.pythonlang.cn/en/latest/specifications/direct-url/#direct-url) 建议在 `direct_url.json` 文件中包含 `archive_info` 的 `hashes` 键，但这不是必需的（根据 [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119.html) 的语言）。

哈希键**应该**以字典的形式存在，将哈希名称映射到文件的十六进制编码摘要。

本 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 与下载轮文件的源位置没有严格的绑定关系，因此我们决定不在 `provenance_url.json` 文件中存储索引 URL。

Conda 中 provenance_url.json 文件的可用性

我们希望从 Conda 维护者那里获得关于 `provenance_url.json` 文件的反馈。目前尚不清楚 Conda 是否希望采用 `provenance_url.json` 文件。Conda 已经将来源相关信息（类似于本 PEP 中提出的来源信息）存储在 `conda-meta` 目录中的 JSON 文件中，[遵循其在安装期间的操作](https://conda.io/projects/conda/en/latest/dev-guide/deep-dives/install.html)。

在后续安装程序中使用 provenance_url.json

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

pip

pip 内部 API 中负责安装轮文件的函数，名为 [_install_wheel](https://github.com/pypa/pip/blob/10d9cbc601e5cadc45163452b1bc463d8ad2c1f7/src/pip/_internal/operations/install/wheel.py#L432)，不会在 `.dist-info` 目录中存储任何 `provenance_url.json` 文件。此外，在 [pypa/pip#11865](https://github.com/pypa/pip/pull/11865) 中向 pip 引入上述文件的原型演示了在 pip 的源代码中合并处理 `provenance_url.json` 文件的逻辑。

由于 pip 被下面提到的某些工具用来安装 Python 包发行版，因此 pip 的发现也适用于这些工具，并且 pip 不允许在其内部 API 中参数化 `.dist-info` 目录中文件的创建。下面提到的大多数使用 pip 的工具都将 pip 作为子进程调用，这对 `provenance_url.json` 文件最终是否出现在 `.dist-info` 目录中没有影响。

distlib

[distlib](https://distlib.readthedocs.io/) 实现用于操作 `dist-info` 目录的底层功能。根据 [distlib 的源代码](https://github.com/pypa/distlib/blob/05375908c1b2d6b0e74bdeb574569d3609db9f56/distlib/database.py#L39-L40)，已安装发行版的数据库不使用任何名为 `provenance_url.json` 的文件。

Pipenv

[Pipenv](https://pipenv.pypa.io/) 使用 pip [安装 Python 包发行版](https://github.com/pypa/pipenv/blob/babd428d8ee3c5caeb818d746f715c02f338839b/pipenv/routines/install.py#L262)。没有发现任何其他已识别的逻辑会导致在 `.dist-info` 目录中引入 `provenance_url.json` 文件时出现向后兼容性问题。

installer

[installer](https://github.com/pypa/installer) 不会显式创建 `provenance_url.json` 文件。然而，根据 [记录已安装的项目](https://packaging.pythonlang.cn/en/latest/specifications/recording-installed-packages/#recording-installed-packages) 规范，installer 允许传递 `additional_metadata` 参数在 `.dist-info` 目录中创建文件 - 请参见 [源代码](https://github.com/pypa/installer/blob/f89b5d93a643ef5e9858a6e3f450c83a57bbe1f1/src/installer/_core.py#L67)。为了避免任何向后兼容性问题，任何使用 installer 的库或工具都不得使用上述 `additional_metadata` 参数请求创建 `provenance_url.json` 文件。

Poetry

[Poetry](https://poetry.pythonlang.cn/) 中的安装逻辑取决于 `installer.modern-installer` 配置选项（[参见文档](https://poetry.pythonlang.cn/docs/configuration#installermodern-installation)）。

当 `installer.modern-installer` 配置选项设置为 `false` 时，Poetry 使用 pip [安装 Python 包发行版](https://github.com/python-poetry/poetry/blob/2b15ce10f02b0c6347fe2f12ae902488edeaaf7c/src/poetry/installation/executor.py#L543-L544)。

另一方面，当 `installer.modern-installer` 配置选项设置为 `true` 时，Poetry 使用 [installer 安装 Python 包发行版](https://github.com/python-poetry/poetry/blob/2b15ce10f02b0c6347fe2f12ae902488edeaaf7c/src/poetry/installation/wheel_installer.py#L99-L109)。从链接的源代码可以看出，没有传递任何名为 `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 编写的，并在安装 wheel 时使用其 自己的安装逻辑。它不会在 .dist-info 目录中创建任何 其他文件，这些文件会与 provenance_url.json 文件名称冲突。