PEP 627 – 记录已安装的项目
- 作者:
- Petr Viktorin <encukou at gmail.com>
- BDFL-代表:
- Paul Moore <p.f.moore at gmail.com>
- 讨论邮件列表:
- Discourse 主题
- 状态:
- 最终
- 类型:
- 标准跟踪
- 主题:
- 打包
- 创建:
- 2020年7月15日
- 决议:
- Discourse 消息
摘要
此 PEP 阐明并更新了 PEP 376（已安装 Python 发行版的数据库），将其重写为互操作性标准。它将标准的规范位置移至 Python 打包机构 (PyPA) 标准存储库，并为更改它设定了指南。
已安装的 .dist-info 目录中的两个文件变为可选：RECORD（PEP 376 将其列为强制性，但建议对于“系统包”可以将其省略）和 INSTALLER。
动机
Python 打包正在从依赖于特定工具（Setuptools 和 pip）转向一个由工具和与工具无关的互操作性标准组成的生态系统。
PEP 376 不是作为互操作性标准编写的。它描述了特定工具和库的实现细节，并且未充分指定，为实现定义的行为留下了很大的空间。
这是一个从 PEP 376 中“提取”标准、澄清它并将其重写为与工具无关的提案。
此 PEP 的目标是拥有一个更好的标准，而不是一个完美的标准。一些问题留待以后澄清。
基本原理变更
PEP 376 的基本原理侧重于两个问题
- 安装项目的方式太多，这使得互操作变得困难。
- 没有 API 来获取有关已安装发行版的信息。
新文档仅关注有关已安装项目的磁盘上格式的信息。提供安装、卸载或查询此信息的 API 留给工具来实现。
标准和变更流程
“记录已安装的项目”（以前称为“已安装 Python 发行版的数据库”）的规范标准是 packaging.python.org 上的 文档。对文档的任何更改（除了琐碎的语言或排版修复）都必须通过 PEP 流程进行。
该文档具有规范性（带有示例以帮助理解）。更改它的 PEP，例如此 PEP，包含预计会过时的其他信息，例如基本原理和兼容性注意事项。
建议的标准与此 PEP 一起作为拉取请求提交到 packaging.python.org。
变更及其基本原理
重命名为“记录已安装的项目”
标准从“已安装 Python 发行版的数据库”重命名为“记录已安装的项目”。
虽然将文件放在磁盘上的已知位置可能被认为是“数据库”，但这并非大多数人在听到该术语时想到的内容。PyPA 在“记录已安装的发行版”标题下链接到 PEP 376。
PyPA 词汇表将“发行版”（或“发行版包”以避免与例如 Linux 发行版混淆）定义为“一个版本化的归档文件 […]”。由于可能存在比从归档文件安装 Python 代码的其他方法，因此文档使用“已安装的项目”而不是“已安装的发行版”。
移除实现细节
所有特定于工具和库的细节都被删除。项目如何安装的机制也被省略：文档侧重于最终状态。一个例外是卸载算法的草图，它用于更好地解释 RECORD 文件的目的。
对 .egg-info 和 .egg 的引用，这些格式特定于 setuptools 和 distutils，被省略。
明确允许附加文件
.dist-info 目录允许包含规范中未指定的其他文件。当前的工具已经这样做。
规范中的一个注释提到了 wheels 的 .dist-info 目录中的文件。当前的工具会将这些文件复制到已安装的 .dist-info 中，这在进一步的标准化工作中需要牢记。
RECORD 文件中的说明
CSV 方言被指定为 Python 的 csv 模块的默认值。这解决了处理文件名中双引号和换行符的极端情况。
RECORD 中相对路径的“基准”相对于 .dist-info 目录指定，而不是特定于工具的 --install-lib 和 --prefix 选项。
哈希和大小字段现在都是可选的（对于任何文件，而不仅仅是 .pyc、.pyo 和 RECORD）。除了 *.pyc 和 RECORD 本身之外，不建议将其省略。（请注意，PEP 376 对哪些是可选的并不清楚；如果按字面意思理解，其文本和示例存在矛盾。尽管如此，“两个字段都是可选的”是对 PEP 376 的合理解释。另一种方法是强制（而不是推荐）哪些文件可以在没有哈希和大小的情况下记录，并随着时间的推移更新该列表，因为新的用例会不断出现。）
新规范明确指出，RECORD 文件现在必须包含已安装项目的所有文件（.pyc 文件的例外情况仍然存在）。由于工具使用 RECORD 进行卸载，因此不完整的文件列表可能会将孤立文件引入用户的环境。另一方面，这意味着如果未知文件的完整列表，则无法记录某些任何文件的哈希值。
包含了一个卸载算法的草图，以阐明该文件的主要目的和内容。
工具不得卸载/删除缺少 RECORD 文件的项目（除非它们具有外部信息，例如在 Linux 发行版的系统包管理器中）。
在 Windows 上，RECORD 中的文件可以用 / 或 \ 分隔。PEP 376 在这一点上并不清楚：它在一个地方强制使用正斜杠，但在 Windows 特定的示例中显示了反斜杠。
可选的 RECORD 文件
RECORD 文件变为可选。并非所有工具都可以轻松地以 Python 特定的格式生成已安装文件的列表。
具体来说，当项目由 Linux 系统打包系统安装时，RECORD 文件是不必要的，该系统有自己的方法来跟踪文件、卸载它们或检查其完整性。必须使 RECORD 文件与磁盘和系统包数据库保持同步将非常脆弱，并且没有 RECORD 文件比一个与现实不符的文件要好。
（完全披露：此 PEP 的作者是 Fedora Linux 发行版中活跃的 RPM 打包人员。）
可选的 INSTALLER 文件
INSTALLER 文件也变为可选，并指定仅用于信息目的。它仍然是一个包含安装程序名称的单行文本文件。
此文件最初是为了区分由 Python 安装程序 (pip) 安装的项目与由其他包管理器（例如 dnf）安装的项目而添加的。有人尝试使用此文件来阻止 pip 更新或卸载它未安装的包。
我们的目标是支持互操作工具，并且基于哪个工具碰巧安装了包来执行任何操作与该目标背道而驰。
工具应使用功能检测而不是依赖于安装程序名称。当前文档提供了一种粗略的方法来使项目无法被 Python 工具触碰：省略 RECORD 文件。
另一方面，安装程序名称可能对用户提示很有用。
为了与该文件的这一新目的保持一致，新规范允许 INSTALLER 中的任何 ASCII 字符串，而不是小写标识符。它还建议使用命令行命令（如果可用）。
REQUESTED 文件：从规范中移除
REQUESTED 文件现在被认为是特定于工具的扩展。
根据 PEP 376，当项目由直接用户请求安装时，而不是为了自动满足另一个项目的依赖关系而安装时，REQUESTED 将被写入。当不再需要时，可以卸载没有此标记文件的项目。
尽管存在标准，但许多现有的安装程序（包括旧版本的pip）从未写入此文件。无法区分“在不再需要时可以删除”的项目和仅由忽略REQUESTED的工具安装的项目。因此，该文件目前无法用于其预期目的（除非某个工具可以使用其他非标准信息）。
澄清
在可能的情况下，术语（例如name和version）通过对现有规范的引用进行限定。
延迟的想法
为了限制本 PEP 的范围，一些改进明确地留待未来的 PEP 处理。
RECORD文件的编码- 限制或命名空间
.dist-info中可以出现的文件。 - 标记用户直接请求安装的项目与为了满足依赖项而安装的项目之间的区别，以便在不再需要时可以删除后者。
版权
本文档放置在公共领域或根据 CC0-1.0-Universal 许可证，以更宽松的许可证为准。
来源：https://github.com/python/peps/blob/main/peps/pep-0627.rst