文件格式

我们希望文件格式在审查锁定文件更改的差异时易于阅读。因此，鉴于 PEP 518 和 pyproject.toml，我们决定采用 TOML 文件格式。

安全设计

将 requirements 文件格式 视为我们最接近锁定文件标准的文件，该文件格式在安全性方面存在一些问题。首先是文件格式根本不要求您指定包的精确版本。这就是为什么存在像 pip-tools 这样的工具来帮助管理 requirements 文件的用户。

其次，您必须通过对特定依赖项使用 --hash 参数来选择指定哪些文件可以安装。这对于 pip-tools 来说也是可选的，因为它需要指定 --generate-hashes CLI 参数。这需要 pip 使用 --require-hashes 以确保没有依赖项缺少哈希值进行检查。

第三，即使您控制了可以安装的文件，它也无法阻止其他软件包的安装。如果依赖项未列在 requirements 文件中，pip 将乐意去寻找文件来满足该需求。您必须将 --no-deps 作为参数传递给 pip，以防止 requirements 文件之外的意外依赖项解析。

第四，该格式允许安装 源分发文件（又称“sdist”）。其本质决定，安装 sdist 需要执行任意 Python 代码，这意味着无法控制将安装哪些文件。只有通过指定 --only-binary :all:，您才能保证 pip 为每个包仅使用 wheel 文件。

总而言之，为了使需求文件与此处提出的建议一样安全，用户应始终执行以下步骤：

1. 使用 pip-tools 及其命令 pip-compile --generate-hashes
2. 使用 pip install --require-hashes --no-deps --only-binary :all: 安装 requirements 文件

至关重要的是，所有这些标志，以及 pip-tools 提供的安装内容的特异性和穷举性，对于 requirements 文件来说都是可选的。

因此，本 PEP 提出的方案是安全设计的，可以应对一些供应链攻击。用于安装文件的哈希值是**必需的**。您**只能**从 wheel 文件安装，以明确定义将放置在文件系统中的文件。安装程序**必须**根据给定平台的锁定文件进行确定性安装。所有这些都导致了可重现的安装，您可以认为它是可信的（当您审核了锁定文件及其列出的内容时）。

跨平台

各种已经有锁定文件的项目，例如 PDM 和 Poetry，提供了 *跨平台* 的锁定文件。这使得一个锁定文件可以在多个平台上工作，同时仍能确保在每个平台上安装完全相同的顶层需求，并且安装结果一致/明确。

至于这为什么有用，让我们举一个涉及 PyWeek（为期一周的游戏开发竞赛）的例子。假设您在 Linux 上开发，而您选择的合作伙伴正在使用 macOS。现在假设评委正在使用 Windows。您如何确保每个人都使用相同的顶层依赖项，同时允许任何平台特定的需求（例如，某个包在 Windows 下需要一个辅助包）？

使用跨平台锁定文件，您可以确保在所有平台上一致地满足关键需求。然后，您还可以确保同一平台上的所有用户获得相同的可重现安装。

简易安装程序

锁定器和安装程序之间的关注点分离使得安装程序执行的操作简单得多。因此，它不仅使安装程序更易于编写，而且有助于确保安装程序正确创建明确、可重现的安装。

安装程序还可以减少创建安装时的计算/能量消耗。这不仅有利于加快安装速度，而且从能耗角度来看也很有益，因为预计安装程序的运行频率会高于锁定器。

这导致了这样一种设计：锁定器必须预先做更多的工作，以利于安装程序。这也意味着包依赖关系的复杂性在锁定文件中更简单、更容易理解，以避免歧义。

详情

锁定文件必须使用 TOML 文件格式。这不仅避免了在 Python 打包生态系统中需要另一种文件格式（因为 PEP 518 为 pyproject.toml 采用了它），而且还有助于使锁定文件更具可读性。

锁定文件的文件名必须以 .pylock.toml 结尾。.toml 部分明确区分了文件的格式，并帮助代码编辑器等工具正确支持该文件。.pylock 部分将该文件与用户拥有的其他 TOML 文件区分开来，使工具更容易创建特定于 Python 锁定文件的功能，而不是一般的 TOML 文件。

以下部分是TOML文件数据格式的顶层键。任何未列为**必需**的字段都被视为可选。

示例

version = "1.0"
created-at = 2021-10-19T22:33:45.520739+00:00

[tool]
# Tool-specific table.

[metadata]
requires = ["mousebender", "coveragepy[toml]"]
marker = "sys_platform == 'linux'"  # As an example for coverage.
requires-python = ">=3.7"

[[package.attrs."21.2.0"]]
filename = "attrs-21.2.0-py2.py3-none-any.whl"
hashes.sha256 = "149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1"
url = "https://files.pythonhosted.org/packages/20/a9/ba6f1cd1a1517ff022b35acd6a7e4246371dfab08b8e42b829b6d07913cc/attrs-21.2.0-py2.py3-none-any.whl"
requires-python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"

[[package.attrs."21.2.0"]]
# If attrs had another wheel file (e.g. that was platform-specific),
# it could be listed here.

[[package."coveragepy[toml]"."6.2.0"]]
filename = "coverage-6.2-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl"
hashes.sha256 = "c7912d1526299cb04c88288e148c6c87c0df600eca76efd99d84396cfe00ef1d"
url = "https://files.pythonhosted.org/packages/da/64/468ca923e837285bd0b0a60bd9a287945d6b68e325705b66b368c07518b1/coverage-6.2-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl"
requires-python = ">=3.6"
requires = ["tomli"]

[[package."coveragepy[toml]"."6.2.0"]]
filename = "coverage-6.2-cp310-cp310-musllinux_1_1_x86_64.whl "
hashes.sha256 = "276651978c94a8c5672ea60a2656e95a3cce2a3f31e9fb2d5ebd4c215d095840"
url = "https://files.pythonhosted.org/packages/17/d6/a29f2cccacf2315150c31d8685b4842a6e7609279939a478725219794355/coverage-6.2-cp310-cp310-musllinux_1_1_x86_64.whl"
requires-python = ">=3.6"
requires = ["tomli"]

# More wheel files for `coverage` could be listed for more
# extensive support (i.e. all Linux-based wheels).

[[package.mousebender."2.0.0"]]
filename = "mousebender-2.0.0-py3-none-any.whl"
hashes.sha256 = "a6f9adfbd17bfb0e6bb5de9a27083e01dfb86ed9c3861e04143d9fd6db373f7c"
url = "https://files.pythonhosted.org/packages/f4/b3/f6fdbff6395e9b77b5619160180489410fb2f42f41272994353e7ecf5bdf/mousebender-2.0.0-py3-none-any.whl"
requires-python = ">=3.6"
requires = ["attrs", "packaging"]

[[package.packaging."20.9"]]
filename = "packaging-20.9-py2.py3-none-any.whl"
hashes.blake-256 = "3e897ea760b4daa42653ece2380531c90f64788d979110a2ab51049d92f408af"
hashes.sha256 = "67714da7f7bc052e064859c05c595155bd1ee9f69f76557e21f051443c20947a"
url = "https://files.pythonhosted.org/packages/3e/89/7ea760b4daa42653ece2380531c90f64788d979110a2ab51049d92f408af/packaging-20.9-py2.py3-none-any.whl"
requires-python = ">=3.6"
requires = ["pyparsing"]

[[package.pyparsing."2.4.7"]]
filename = "pyparsing-2.4.7-py2.py3-none-any.whl"
hashes.sha256 = "ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
url = "https://files.pythonhosted.org/packages/8a/bb/488841f56197b13700afd5658fc279a2025a39e22449b7cf29864669b15d/pyparsing-2.4.7-py2.py3-none-any.whl"
direct = true  # For demonstration purposes.
requires-python = ">=2.6, !=3.0.*, !=3.1.*, !=3.2.*"

[[package.tomli."2.0.0"]]
filename = "tomli-2.0.0-py3-none-any.whl"
hashes.sha256 = "b5bde28da1fed24b9bd1d4d2b8cba62300bfb4ec9a6187a957e8ddb9434c5224"
url = "https://files.pythonhosted.org/packages/e2/9f/5e1557a57a7282f066351086e78f87289a3446c47b2cb5b8b2f614d8fe99/tomli-2.0.0-py3-none-any.whl"
requires-python = ">=3.7"

锁定工具的期望

锁定器必须创建锁定文件，该文件应满足以下条件：对在指定平台上符合安装条件的软件包进行拓扑排序后，生成的图只能包含每个软件包的一个版本，并且每个软件包至少有一个兼容的安装文件。这使得任何受支持平台上的锁定文件，安装程序唯一可以做的决定就是安装哪个“最适合”的 wheel（这将在下面讨论）。

锁定器应酌情使用 metadata.marker、metadata.tag 和 metadata.requires-python，以及通过 requires 指定的环境标记和通过 requires-python 指定的 Python 版本要求，以强制安装程序达到此结果。换句话说，锁定文件中使用的信息不应是锁定器输入的原始/纯净信息，而应根据锁定器目标进行必要的更改。

安装程序的期望

预期解决安装内容的算法如下：

1. 根据锁定文件中的数据，以 metadata.requires 为起始/根节点构建一个依赖图。
2. 消除所有指定平台不支持的文件。
3. 根据 requires 的标记评估结果，消除所有包之间不相关的边。
4. 如果包版本仍然可以从依赖图的根节点到达，但缺少任何兼容文件，则抛出错误。
5. 验证所有剩余的包只剩下一个版本可供安装，否则抛出错误。
6. 安装每个剩余包的最佳适配 wheel 文件。

安装程序**必须**遵循确定性算法来确定“最适合的 wheel 文件”。一个简单的解决方案是依赖 packaging project 及其 packaging.tags 模块来确定 wheel 文件的优先级。

安装程序**必须**支持安装到空环境中。安装程序**可以**支持安装到已包含已安装软件包的环境中（以及为支持此操作可能需要的任何内容）。

可用性

首先，可以开发一个等同于 pip freeze 的工具，它会创建一个锁定文件。虽然已安装的包本身无法提供足够的信息来静态创建锁定文件，但用户可以提供本地目录和索引 URL 来构建一个。这将导致锁定文件比 requirements 文件更严格，因为它将锁定文件限制在当前平台。这也将让人们看到他们的环境是否可重现。

其次，应开发一个独立的安装程序。由于安装程序的要求比 pip 提供的要简单得多，因此开发一个独立的安装程序应该是合理的。

第三，可以开发一个工具，用于转换由 pip-tools 生成的固定版本需求文件。与上面概述的 pip freeze 等效工具类似，可能需要用户的一些输入。但是，此工具可以作为拥有合适需求文件的任何人的过渡步骤。这也可以作为在 pip-tools 考虑添加 --lockfile 标志以使用此 PEP 之前的测试。

所有这些可能需要在 PEP 从有条件接受过渡到完全接受之前完成（并给社区一个机会来测试这个 PEP 是否可能有用）。

互操作性

此时，目标将是增加工具之间的互操作性。

首先，pip 将成为一个安装程序。通过让最广泛使用的安装程序支持该格式，人们可以在锁定器方面进行创新，同时知道人们将拥有实际使用锁定文件所需的工具。

其次，pip 成为一个锁定器。再一次，pip 的影响力将使绝大多数 Python 用户能够非常快速地访问该格式。

第三，一个具有预先存在的锁定文件格式的项目至少支持导出到该锁定文件格式（例如 PDM 或 Pyflow）。这将表明该格式满足了其他项目的需求。

接受

随着整个社区提供工具，接受度将通过那些不完全受限于 Python 社区的工具对文件格式的支持来体现，这基于他们认为用户需要什么。

首先，像代码编辑器这样操作需求文件的工具，对锁定文件也有同等支持。

其次，像云提供商这样的需求文件使用者也会接受锁定文件。

此时，该 PEP 将已足够普及，在普遍接受度方面与需求文件不相上下，如果项目放弃了自己的锁定文件而采用此 PEP，则可能更受欢迎。

除TOML之外的文件格式

曾短暂考虑过 JSON，但由于

1. TOML 已用于 pyproject.toml
2. TOML 更易读
3. TOML 产生更好的差异

因此决定使用 TOML。有人担心 Python 的标准库缺少 TOML 解析器，但由于 pyproject.toml，大多数打包工具已经使用了 TOML 解析器，因此这个问题似乎不是一个障碍。过去也有人反驳这种担忧，理由是如果打包工具厌恶安装依赖项并且觉得它们不能供应商化一个包，那么打包生态系统需要解决比依赖第三方 TOML 解析器更大的问题。

替代命名方案

曾考虑过指定安装文件的目录，但最终因人们对此想法的厌恶而被拒绝。

也有人建议不使用特殊的文件名后缀，但最终认为这会严重影响工具的可发现性。

支持单个锁定文件

曾一度考虑只支持一个包含所有可能锁定信息的单一锁定文件。但很快就发现，试图设计一种数据格式，既能支持多种环境的锁定文件格式，又能支持可重现构建的严格锁定结果，将变得相当复杂和笨重。

也曾考虑支持一个包含锁定文件的目录，以及一个名为 pyproject-lock.toml 的单一锁定文件。但如果只有一个锁定文件，跳过目录可能带来的任何简化似乎都没有必要。试图定义 pyproject-lock.toml 文件中应该包含什么以及 pyproject-lock.d 中应该包含什么的适当逻辑，似乎不必要地复杂。

使用平面列表而不是依赖图

本 PEP 的第一个版本提出，锁定文件不应具有依赖图的概念。相反，锁定文件将精确列出特定平台应安装的内容，这样安装程序就不必决定 *安装什么*，只需验证锁定文件是否适用于目标平台。

这个想法最终被拒绝了，原因是潜在的 PEP 508 环境标记组合数量太多。最终决定，当项目希望跨平台时，试图让锁定器生成所有可能的组合作为单独的锁定文件将过于繁重。

在文件名中使用 Wheel 标签

最初建议将标签编码到文件名中，而不是使用 metadata.tag 字段。但由于添加了 metadata.marker 字段以及在不需要标签时如何处理的问题，这个想法被放弃了。

requires 的替代名称

用于表示 requires 的其他名称有 installs、needs 和 dependencies。最初，此 PEP 在询问一位 Python 初学者他们更喜欢哪个术语后选择了 needs。但根据对此 PEP 早期草案的反馈，最终选择了 requires。

接受 PEP 650

PEP 650 是一个早期的尝试，试图通过为安装程序指定 API 而不是标准化锁定文件格式来解决这个问题（类似于 PEP 517）。对 PEP 650 的 最初回应 可以说是温和/平淡。人们似乎一直对哪些工具应该提供什么功能来实施 PEP 感到困惑。它还可能带来更多的开销，因为它需要执行 Python API 来执行任何涉及打包的操作。

此 PEP 选择围绕一个制品而不是 API 进行标准化（类似于 PEP 621）。这将允许更多的工具集成，因为它消除了专门使用 Python 来创建锁定文件、更新它甚至安装锁定文件中列出的包的需求。它还通过强制将依赖图细节以人类可读的格式编写来方便内省。它还通过标准化人们需要了解的更多内容来促进知识共享（例如，当涉及到理解它们产生的制品时，教程在不同工具之间更具可移植性）。这也很简单，是其他语言社区所采取并似乎满意的做法。

接受此 PEP 将意味着 PEP 650 被拒绝。

按包而非按文件指定需求

本 PEP 的早期草案是在包级别而非每个文件级别指定依赖项。虽然这传统上是打包系统的工作方式，但它实际上并没有准确反映事物是如何指定的。因此，本 PEP 随后进行了更新，以反映依赖项可以真正指定到的粒度。

指定锁定器收集输入的位置

本 PEP 未指定锁定器如何获取其输入。最初的建议是部分重用 PEP 621，但由于在指定索引等方面的潜在输入灵活性存在分歧，因此决定将此问题留给单独的 PEP 处理。

允许源分发和源树作为可选支持的文件格式

经过 广泛讨论 后，决定此 PEP 不支持源分发 (sdist) 或源树作为可接受的代码格式。将 sdist 和源树引入此 PEP 将立即破坏可重现性和安全性目标，因为需要执行代码来构建 sdist 或源树。它还将大大增加（至少是）安装程序的复杂性，因为 sdist 和源树的动态构建性质意味着安装程序需要完全解决 sdist 动态产生的所有需求，无论是从构建还是安装的角度。

鉴于所有这些，决定最好在**此 PEP 接受/拒绝之后**，就支持 sdist 和源树进行单独的讨论。由于提议的文件格式是版本化的，因此在未来的 PEP 中引入 sdist 和源树支持是可行的。

然而，应该注意的是，此 PEP **不**阻止开发与此 PEP 结合使用的带外解决方案。从 sdist 构建 wheel 文件并在部署时随代码一起交付，以便它们可以包含在锁定文件中，这是一个选项。另一个是 *仅* 对 sdist 和源树使用 requirements 文件，然后对所有 wheel 依赖锁定文件。