了解 Python 的新锁文件格式

新批准的 Python 增强提案 751 为 Python 提供了一种用于指定项目依赖项的标准锁定文件格式。以下是内容、原因和时间。

Python 增强提案 (PEP) 751为 Python 提供了一种用于指定依赖项的新文件格式。

此文件称为锁定文件，它承诺允许开发人员在不同系统之间重现其 Python 项目的安装，并具有完全相同的依赖项集。

PEP 751 – A file format to record Python dependencies for installation reproducibility | peps.python.org

尽管有几种社区解决方案，但 Python 历来缺乏一种官方方法来执行文件锁定和依赖项冲突解决。

最接近本机解决方案的是 requirements.txt 文件或 的输出 pip freeze。该 requirements.txt 文件列出了项目的要求以及每个要求的可能版本范围。

但它没有解决这些要求应该来自哪里、如何根据哈希验证它们，或者当今锁定文件通常解决的许多其他需求。

个别项目管理工具（如 Poetry） uv 会尽力解决依赖项之间的冲突，并将其记录在锁定文件中。

坏消息是：这些锁定文件没有通用格式，因此它们不能在工具之间互换。它们通常由每个用户在安装项目要求时就地创建，而不是由开发人员创建并重新分发。

什么是锁文件以及它为何重要

无论项目建立在何处，锁定文件都可让项目的依赖项可靠地重现。

理想情况下，锁定文件会列出每个依赖项、查找位置、用于验证的哈希值，以及重新创建依赖项集可能需要的任何其他信息。

Python 项目通常没有 JavaScript 项目中可能出现的大量、杂乱的依赖项集。但即使只有少量依赖项的项目也可能存在冲突。

假设您有一个名为 的依赖项 fixthis，而该依赖项又依赖于名为 fixerupper 的包 。但是， 具体fixthis 依赖于 1.5 版本 ，因为更高版本的行为 尚未解决。fixerupper fixthis 这本身不是问题，因为您只需安装 fixthis 并自动安装 1.5 版即可。当项目中的其他 fixerupper 依赖项也可能使用时，问题就出现了 。

假设我们在项目中添加另一个依赖项， fixthat 它也依赖于 fixerupper。但是，fixthat 只适用于 2.0 或更高版本的 fixerupper。这意味着 fixthis 和 fixthat 不能共存。

另一方面，假设我们有一个替代包， fixit它可以与 1.5 版 fixerupper 或更高版本一起使用。

那么都和 fixthis 可以 fixit 与 1.5 版一起使用 fixerupper。

我们项目的锁定文件可以记录解决此冲突的方式，从而允许其他用户安装完全相同的依赖项和版本，以避免任何死锁或冲突。

PEP 751 对 Python 的作用

PEP 751 自 2024 年 7 月以来经过多次反复最终确定，描述了 Python 项目的通用锁文件格式，以解决上述许多问题。

该文件通常名为 pylock.toml，使用 TOML 数据格式，就像标准 Python 项目描述文件 一样 pyproject.toml。

pylock.toml文件可以手写，但我们的想法是，您不必这样做。现有工具将及时自动生成 ，就像可以从项目的虚拟环境中生成文件 pylock.toml 一样。

requirements.txt pip freeze

该 pylock.toml 文件允许提供各种详细信息。它可以指定要使用哪个版本的锁定文件标准（如果将来发生变化），要使用哪个版本的 Python，要尊重不同 Python 版本的哪些 环境标记 ，以及大部分此类信息的包级说明符。

每个指定的依赖项都可以包含有关其来源（包括来自版本控制系统）、哈希、源分发信息（如果有）等的详细信息。

PEP 751 中提供了 pylock.toml 该格式的详细示例。每个依赖项都有自己的小节，其中包含有关获取位置和时间、哈希值、版本要求等的详细信息。

该示例展示了一个包如何拥有多个特定于平台的源。在该示例中，列出了适用于 Microsoft Windows 和通用 Linux 系统的二进制轮子。

PEP 751 – A file format to record Python dependencies for installation reproducibility | peps.python.org

PEP 751 锁文件何时到达？

截至撰写本文时，目前还没有官方或第三方工具支持 pylock.toml。

从现在开始，工具的未来修订版 pip 都将 pylock.toml 按照其提供商认为合适的速度进行，因此您可以期待新的锁定文件随着时间的推移添加到工作流程和项目组成中。

您最终会想考虑项目的依赖项集是否足够复杂，需要文件 pylock.toml 。例如，任何创建托管在 PyPI 上的包的人都会倾向于 pylock.toml 为项目创建一个。

采用的速度将取决于现有工具多快能够生成 pylock.toml 文件，以及该文件格式是否会立即取代它们自己的内部格式。

一些生成自己的锁文件的第三方工具仍犹豫是否将其用作 pylock.toml 完全替代品。 

例如，打算支持将其 pylock.toml 作为导出和导入格式，但不将其作为其原生锁文件的格式， 因为中尚不支持某些功能 pylock.toml。但是，完全有可能在规范的未来修订版中添加对这些功能的支持 pylock.toml 。