PEP 503 – 简单仓库 API
- 作者:
- Donald Stufft <donald at stufft.io>
- BDFL 代表:
- Donald Stufft <donald at stufft.io>
- 讨论邮件列表:
- Distutils-SIG 邮件列表
- 状态:
- 最终
- 类型:
- 标准跟踪
- 主题:
- 打包
- 创建:
- 2015-09-04
- 发布历史:
- 2015-09-04
- 决议:
- Distutils-SIG 消息
摘要
Python 包仓库有很多实现，也有很多工具使用它们。其中，定义“简单”仓库 API 的规范实现是为 PyPI 提供支持的实现。本文档将指定该 API，记录任何简单仓库 API 实现的正确行为。
规范
实现简单 API 的仓库由其基本 URL 定义，这是所有其他 URL 所在的顶级 URL。该 API 被命名为“简单”仓库，因为 PyPI 的基本 URL 是 https://pypi.ac.cn/simple/。
注意
本文档中的所有后续 URL 都是相对于此基本 URL 的（因此，给定 PyPI 的 URL，/foo/ 的 URL 将是 https://pypi.ac.cn/simple/foo/）。
在仓库中，根 URL（对于此 PEP 表示基本 URL 的 /）**必须**是一个有效的 HTML5 页面，每个项目在仓库中都有一个锚元素。锚标记的文本**必须**是项目的名称，href 属性**必须**链接到该项目的 URL。例如
<!DOCTYPE html>
<html>
<body>
<a href="/frob/">frob</a>
<a href="/spamspamspam/">spamspamspam</a>
</body>
</html>
根 URL 下是仓库中每个项目的另一个 URL。此 URL 的格式为 /<project>/，其中 <project> 被项目的规范化名称替换，因此名为“HolyGrail”的项目将有一个类似于 /holygrail/ 的 URL。此 URL 必须响应一个有效的 HTML5 页面，该页面为项目中的每个文件包含一个锚元素。href 属性**必须**是一个链接到文件下载位置的 URL，锚标记的文本**必须**与 URL 的最终路径组件（文件名）匹配。URL**应该**包含一个以 URL 片段形式存在的哈希，其语法如下：#<hashname>=<hashvalue>，其中 <hashname> 是哈希函数的小写名称（例如 sha256），而 <hashvalue> 是十六进制编码的摘要。
除了上述内容外，还对 API 施加了以下约束
- 所有以 HTML5 页面响应的 URL**必须**以
/结尾，并且仓库**应该**重定向没有/的 URL 以在末尾添加/。 - 只要 URL 指向正确的位置，它们就可以是绝对的或相对的。
- 对文件相对于仓库的托管位置没有限制。
- 只要存在所需的锚元素，API 页面上可以有任何其他 HTML 元素。
- 仓库**可以**将未规范化的 URL 重定向到规范化的 URL（例如，
/Foobar/可以重定向到/foobar/），但是客户端**绝不能**依赖此重定向，并且**必须**请求规范化的 URL。 - 仓库**应该**从 Python 标准库中
hashlib模块保证可用的哈希函数之一中选择哈希函数（目前为md5、sha1、sha224、sha256、sha384、sha512）。目前的建议是使用sha256。 - 如果某个发行版文件有 GPG 签名，则**必须**与该文件一起存在，名称相同，并在其后附加
.asc。因此，如果文件/packages/HolyGrail-1.0.tar.gz存在并具有关联签名，则签名将位于/packages/HolyGrail-1.0.tar.gz.asc。 - 仓库**可以**在文件链接上包含一个
data-gpg-sig属性，其值为true或false，以指示是否存在 GPG 签名。执行此操作的仓库**应该**在每个链接上包含它。 - 仓库**可以**在文件链接上包含一个
data-requires-python属性。这公开了在 PEP 345 中指定的对应版本的Requires-Python 元数据字段。在出现此属性时，安装程序工具**应该**在安装到不满足要求的 Python 版本时忽略下载。例如<a href="..." data-requires-python=">=3">...</a>
在属性值中，< 和 > 必须分别以 HTML 编码的形式出现为
<和>。
规范化名称
此 PEP 引用了“规范化”项目名称的概念。根据 PEP 426，名称中唯一有效的字符是 ASCII 字母、ASCII 数字、.、- 和 _。名称应小写，所有 .、- 或 _ 字符串都应替换为单个 - 字符。这可以使用 Python 的 re 模块实现
import re
def normalize(name):
return re.sub(r"[-_.]+", "-", name).lower()
变更
- 可选的
data-requires-python属性于 2016 年 7 月添加。
版权
本文档已置于公共领域。
来源：https://github.com/python/peps/blob/main/peps/pep-0503.rst