文件格式

我们希望文件格式在审核对锁定文件的更改时易于作为差异查看。因此，并且感谢 PEP 518 和 pyproject.toml，我们决定使用 TOML 文件格式。

天生安全

将 需求文件格式 视为我们最接近锁定文件标准的内容，在安全性方面，该文件格式存在一些问题。首先，该文件格式根本不需要您指定包的确切版本。这就是 pip-tools 之类的工具存在的理由，以帮助管理需求文件用户。

其次，您必须选择使用特定依赖项的 --hash 参数来指定哪些文件可接受安装。这在 pip-tools 中也是可选的，因为它需要指定 --generate-hashes CLI 参数。这需要 --require-hashes 才能让 pip 确保没有依赖项缺少要检查的哈希值。

第三，即使您控制了哪些文件可以安装，也不会阻止安装其他包。如果需求文件中未列出依赖项，pip 将很乐意搜索满足该需求的文件。您必须指定 --no-deps 作为 pip 的参数以防止在需求文件之外意外解决依赖项。

第四，该格式允许安装 源代码分发文件（也称为“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: 安装需求文件

至关重要的是，所有这些标志以及 pip-tools 提供的安装内容的具体性和详尽性，对于需求文件都是可选的。

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

跨平台

一些已经具有锁定文件的项目，例如 PDM 和 Poetry，提供了跨平台的锁定文件。这允许单个锁定文件在多个平台上工作，同时仍然导致在所有地方安装完全相同的顶级依赖项，并在每个平台上保持安装的一致性/明确性。

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

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

简单的安装程序

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

安装程序还可以减少创建安装所需的计算/能量。这不仅有利于更快地安装，而且从能耗的角度来看也是有益的，因为安装程序预计比锁定程序运行得更频繁。

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

细节

锁定文件**必须**使用 TOML 文件格式。这不仅避免了由于 PEP 518 在 pyproject.toml 中采用了 TOML 而需要在 Python 打包生态系统中引入其他文件格式，而且还有助于使锁定文件更易于人工阅读。

锁定文件**必须**以 .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 项目及其packaging.tags模块来确定 wheel 文件的优先级。

安装程序**必须**支持安装到空环境中。安装程序**可以**支持安装到已经包含已安装包的环境中（以及支持该操作所需的任何内容）。

可用性

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

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

第三，可以开发一个工具来转换 pip-tools 发出的固定需求文件。与上面概述的pip freeze等效工具类似，可能需要用户提供一些输入。但是，此工具可以作为任何具有适当需求文件的用户的过渡步骤。这也可以作为在 pip-tools 可能增加一些--lockfile标志来使用该PEP之前的测试。

在PEP从条件接受过渡到完全接受之前，所有这些都可能是必需的（并让社区有机会测试该PEP是否可能有用）。

互操作性

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

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

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

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

验收

随着整个社区中工具的可用性，接受度将通过那些并非完全依赖于 Python 社区的用户根据他们认为用户想要的内容来支持文件格式来体现。

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

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

此时，PEP 将渗透得足够远，在普遍接受度方面与需求文件相当，如果项目已将其自己的锁定文件替换为此PEP，则可能更高。

除 TOML 之外的文件格式

JSON曾被短暂考虑过，但由于

1. pyproject.toml已在使用 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 文件。