PEP 629 – PyPI 简单 API 版本控制

注意

此 PEP 于 2020-08-20 被接受。PyPI 于 2020-01-28 合并了一个实现，将此 PEP 标记为“最终”。

摘要

此 PEP 提出添加一种简单 API 版本控制方法，以便客户端可以确定特定存储库支持的简单 API 功能。

在改进简单 API 时，客户端希望能够确定存储库支持哪些功能。目前没有机制可以做到这一点，除非尝试通过查看响应中的数据来检测新功能，并查看是否似乎正在使用特定功能。

对于现代版本的客户端来说，这在确定存储库是否支持其想要实现的所有功能方面效果相当好，但是它没有做任何事情来告诉客户端的旧版本存储库支持它可能不理解的功能，并允许消息传递表明它可能无法正确理解存储库的输出。

一个发生这种情况的场景示例是 python-requires 元数据的逐步引入，虽然现有客户端仍然可以成功使用存储库，但他们缺乏理解此新数据的能力，而这将影响他们的行为以选择更适合最终用户的文件。

此 PEP 提出在每个对简单 API 页面成功请求的响应中包含一个元标记，该标记包含一个名为“pypi:repository-version”的属性，以及一个内容，该内容是 PEP 440 兼容的版本号，并且进一步限制为仅为主版本.次版本，而不是 PEP 440 支持的其他功能。

最终将如下所示

<meta name="pypi:repository-version" content="1.0">

在解释存储库版本时

任何未来的 PEP 都有权自行决定什么具体构成不兼容与兼容的更改，超出了现有客户端将能够“有意义地”继续使用 API 的广泛建议，并且可以包括添加、修改或删除现有功能。

此 PEP 预计主版本永远不会增加，并且任何未来的主要 API 演变都将使用不同的 API 演变机制。但是，主版本包含在内是为了与未来版本区分开来（例如，假设一个位于 /v2/ 的简单 api v2，但如果存储库版本设置为大于或等于 2 的版本，则会令人困惑）。

此 PEP 将当前 API 版本设置为“1.0”，并期望未来进一步改进简单 API 的 PEP 将增加次版本号。

与简单 API 交互的客户端**应该**检查每个响应的存储库版本，如果该数据不存在，**必须**假设它是版本 1.0。

遇到大于预期的主版本时，客户端**必须**以适合用户的错误消息硬性失败。

遇到大于预期的次版本时，客户端**应该**向用户发出适当的消息。

客户端**可以**继续使用功能检测来确定存储库使用哪些功能。