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 范围请求部分下载轮子的方法来减少下载大小。然而，这为仓库服务器添加了额外的运行时需求。它仍然会增加额外的开销，因为需要一个单独的请求来获取轮子的文件列表，以找到获取元数据文件的正确偏移量。因此，需要服务器提前提取元数据文件，并将其作为独立文件提供，以避免执行额外的请求和 ZIP 检查。

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

发行版文件的锚点链接上需要一个 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 作为属性的值，如果哈希值不可用。