摘要

此 PEP 重命名了PEP 658 在简单 API 的 HTML 和 JSON 格式中提供的元数据，并为客户端和服务器如何处理重命名提供了指导。

动机

PEP 658 指定了一种机制来托管通过简单 API 可用的工件的核心元数据文件，以便客户端可以获取元数据并在不下载整个工件的情况下使用它。后来编写了PEP 691 来添加在简单 API 上使用 JSON 而不是 HTML 的功能，其中包括对PEP 658 元数据的支持。

不幸的是，PyPI 直到最近才支持PEP 658，它发布时存在一个错误，其中来自PEP 658 的dist-info-metadata 键在 JSON 表示中被错误地命名为data-dist-info-metadata。但是，在尝试修复该错误时，发现 pip 也存在一个错误，即在 JSON 表示中使用dist-info-metadata 会导致 pip 出现异常并硬性失败。

pip 中的错误至少从v22.3版本就存在，这意味着它已经发布了大约 8 个月，足够长的时间被包含到 Python 版本、下游 Linux 版本、容器中、虚拟环境等。

这使我们陷入了一个尴尬的境地，即 PyPI 上存在一个无法修复的错误，因为它会导致 pip 出现故障，而 pip 的这个版本已经发布了足够长的时间，并被广泛部署。更糟糕的是，一旦 pip 修复了其错误，则此版本的 pip 就无法从 PyPI 安装任何内容，包括安装新的、已修复的 pip 版本。

基本原理

对于修复这些错误，有三个主要的选择

1. 不要更改规范，修复 pip 中的错误，等待一段时间，然后修复 PyPI 中的错误，从而导致任何使用未修复 pip 的用户无法甚至从 PyPI 安装新的 pip。
2. 与 (1) 相同，但对 PyPI 进行特殊情况处理，即使可用，它也不会为 pip 发出PEP 658 元数据。这允许用户如果使用的是已损坏的版本则可以升级 pip，但其他任何操作都不行。
3. 更改规范以避免 pip 目前无法处理的密钥，允许 PyPI 发出该密钥并发布新的 pip 版本以利用该密钥。

此 PEP 选择 (3)，但更进一步，还在 HTML 表示中重命名了密钥。

通常，我们不会因为仅影响一个特定实现的错误而更改规范，除非规范本身有错，而这里并非如此：规范很好，这些只是 pip 和 PyPI 中的真正错误。

但是，我们选择这样做有四个原因

1. 影响 pip 和 PyPI 的错误与任何其他客户端或存储库组合相比，其影响更大。
2. 损坏的影响是安装根本无法工作，而不是以某种方式优雅地降级。
3. 这些错误阻止的功能对于能够快速有效地解决来自 PyPI 的 pip 依赖关系非常重要，并且不得不延迟很长时间等待 pip 的损坏版本停止使用会损害整个生态系统。
4. 鉴于我们认为对它的支持并不广泛，因此更改规范的缺点相当有限，因此它仅影响有限数量的项目。

规范

本文档中的关键词“**必须**”、“**禁止**”、“**需要**”、“**应该**”、“**不应该**”、“**建议**”、“**不建议**”、“**推荐**”、“**可以**”和“**可选**”应按RFC 2119 中的描述进行解释。

向后兼容性

此 PEP 中存在一个小的兼容性中断，即当前正确处理现有元数据密钥的客户端不会自动理解更新的元数据密钥，但它们应该优雅地降级，并简单地将其视为PEP 658 元数据不存在。

否则，此 PEP 不应该存在任何兼容性问题。

被拒绝的想法

建议

本节中的建议（除了本通知本身）是非规范性的，代表 PEP 作者认为对于实现此 PEP 的内容的最佳默认实现决策，但它并不代表任何与这些决策相匹配的要求。

版权

本文档置于公共领域或根据 CC0-1.0-Universal 许可证，以更宽松者为准。