PEP 629 – PyPI Simple API 版本控制
- 作者:
- Donald Stufft <donald at stufft.io>
- BDFL 委托：
- Brett Cannon <brett at python.org>
- 讨论至:
- Discourse 帖子
- 状态:
- 最终版
- 类型:
- 标准跟踪
- 主题:
- 打包
- 创建日期:
- 2020年7月16日
- 发布历史:
- 2020年7月16日
注意
此 PEP 已于 2020年8月20日被接受。PyPI 于 2020年1月28日 合并了一个实现，标志着此 PEP 为“最终”。
摘要
本 PEP 提议为 simple API 添加一种版本控制方法，以便客户端可以确定特定仓库支持 simple API 的哪些功能。
基本原理
在发展 simple API 时，客户端希望能够确定仓库支持哪些功能。目前没有机制可以做到这一点，除了通过查看响应中的数据来尝试检测新功能，并查看是否似乎正在使用特定功能。
这对于现代版本的客户端来说，可以很好地确定仓库是否支持它想要实现的所有功能，但它无法告诉旧版本客户端仓库支持它可能无法理解的功能，也无法允许消息传递来表明它可能无法正确理解仓库的输出。
一个发生这种情况的场景是 `python-requires` 元数据逐步推出，虽然现有客户端仍然可以成功使用仓库，但它们缺乏理解这块新数据的能力，而这些数据本可以指导它们的行为，为最终用户选择更好的文件。
概述
本 PEP 提议在对 simple API 页面的每个成功请求的响应中包含一个 meta 标签，其中包含一个 `name` 属性为“pypi:repository-version”，以及一个内容是 PEP 440 兼容的版本号，并且进一步限制为仅为 Major.Minor，不包含 PEP 440 支持的任何附加功能。
这看起来会像
<meta name="pypi:repository-version" content="1.0">
在解释仓库版本时
- 增加主版本号用于表示向后不兼容的更改，这意味着现有客户端将不再能有意义地使用该 API。
- 增加次版本号用于表示向后兼容的更改，这意味着现有客户端仍然可以有意义地使用该 API。
至于具体构成向后不兼容还是兼容的更改，除了现有客户端将能够“有意义地”继续使用 API 的广泛建议之外，将由任何未来的 PEP 自行决定，并且可以包括添加、修改或删除现有功能。
本 PEP 期望主版本号永远不会增加，并且任何未来的主要 API 演进都将利用不同的 API 演进机制。然而，包含主版本号是为了与未来版本区分开来（例如，一个假设的 simple API v2 存在于 `/v2/`，但如果 `repository-version` 设置为 >= 2 的版本，则会令人困惑）。
本 PEP 将当前的 API 版本设置为“1.0”，并期望未来进一步发展 simple API 的 PEP 将增加次版本号。
客户端
与 simple API 交互的客户端 **应该** 检查每个响应中的仓库版本，如果该数据不存在，则 **必须** 假定其版本为 1.0。
当遇到大于预期版本的主版本号时，客户端 **必须** 带着适当的错误信息硬失败（立即中止）。
当遇到大于预期的次版本号时，客户端 **应该** 向用户发出适当的警告消息。
客户端 **可以** 仍然继续使用功能检测来确定仓库使用了哪些功能。
被拒绝的想法
使用 HTTP 头部
除了将此信息嵌入到实际的 HTML 中，另一种选择是使用 HTTP 头部。这个想法被考虑过，但最终被拒绝，因为它会使镜像不得不开始修改头部，而不是能够充当“傻瓜式”的文件 HTTP 服务器。
使用 URL
另一种传统的 API 版本控制机制是将其嵌入到 URL 中，例如 /1.0/simple/ 等。这对于主要版本更改非常有效，因为旧的客户端预计无法继续使用它，但它不适用于次要版本升级，特别是当版本号在很大程度上可以被视为对最终用户的建议时。
版权
本文档置于公共领域或 CC0-1.0-Universal 许可证下，以更宽松者为准。
来源：https://github.com/python/peps/blob/main/peps/pep-0629.rst