PEP 658 – 在简单仓库 API 中提供分发元数据

作者:: Tzu-ping Chung <uranusjr at gmail.com>
发起人:: Brett Cannon <brett at python.org>
PEP 代理人:: Donald Stufft <donald at stufft.io>
讨论至:: Discourse 帖子
状态:: 已接受
类型:: 标准跟踪
主题:: 打包
创建日期:: 2021年5月10日
发布历史:: 2021年5月10日
决议:: Discourse 消息

摘要
动机
基本原理
规范
向后兼容性
被拒绝的想法
参考资料
版权

摘要

本 PEP 提议添加一个锚点标签，以在 PEP 503 “简单”仓库 API 中公开分发中的 METADATA 文件。引入了一个 data-dist-info-metadata 属性，用于指示给定分发中的文件可以独立获取。

动机

最近工具普及的包管理工作流增加了在不打算安装分发的情况下检查分发元数据的需求，并下载项目的多个分发以根据其元数据进行选择。这意味着它们最终会丢弃大量已下载的数据，这效率低下并导致糟糕的用户体验。

基本原理

工具一直在探索通过 HTTP 范围请求部分下载 wheel 来减少下载大小的方法。然而，这增加了仓库服务器的额外运行时要求。它也仍然增加了额外的开销，因为需要单独的请求来获取 wheel 的文件列表以找到获取元数据文件的正确偏移量。因此，希望服务器提前提取元数据文件，并将其作为独立文件提供，以避免执行额外请求和 ZIP 检查的需求。

由核心元数据规范 [core-metadata] 定义的元数据文件将由仓库直接提供，因为它包含常见用例的必要信息。元数据必须仅用于符合标准的分发，例如 wheel [wheel] 和 sdist [sdist]，并且必须与分发的规范元数据文件相同，例如 wheel 的 .dist-info 目录 [dist-info] 中的 METADATA 文件。

分发文件的锚点链接上需要一个 HTML 属性，以指示客户端是否能够选择单独提供的元数据文件。该属性还用于提供元数据内容的哈希值以进行客户端验证。该属性的缺失表示该分发没有单独的元数据条目，原因可能是分发的内容或缺少仓库支持。

规范

在简单仓库的项目页面中，每个指向分发的锚点标签可以拥有一个 data-dist-info-metadata 属性。该属性的存在表明由锚点标签表示的分发必须包含一个核心元数据文件，该文件在分发被处理和/或安装时不会被修改。

如果存在 data-dist-info-metadata 属性，仓库必须将分发的核心元数据文件与分发一起提供，并在分发文件名后附加 .metadata。例如，位于 /files/distribution-1.0-py3.none.any.whl 的分发的核心元数据将位于 /files/distribution-1.0-py3.none.any.whl.metadata。这类似于 PEP 503 指定 GPG 签名文件位置的方式。

仓库应该使用语法 <hashname>=<hashvalue> 将核心元数据文件的哈希值作为 data-dist-info-metadata 属性的值，其中 <hashname> 是所用哈希函数的小写名称，<hashvalue> 是十六进制编码的摘要。如果哈希值不可用，仓库可以使用 true 作为属性值。