PEP 503 – 简单仓库 API

作者:: Donald Stufft <donald at stufft.io>
BDFL 委托：: Donald Stufft <donald at stufft.io>
讨论至:: Distutils-SIG 邮件列表
状态:: 最终版
类型:: 标准跟踪
主题:: 打包
创建日期:: 2015年9月4日
发布历史:: 2015年9月4日
决议:: Distutils-SIG 消息

摘要
规范
- 规范化名称
- 更改
版权

重要

本 PEP 是一份历史文档。最新的规范《简单仓库 API》在 PyPA 规范页面上维护。

有关如何提出更改的建议，请参阅PyPA 规范更新流程。

摘要

Python 包仓库有许多实现，也有许多工具使用它们。其中，定义“简单”仓库 API 样子的规范实现是支持 PyPI 的实现。本文档将指定该 API，记录任何简单仓库 API 实现的正确行为。

规范

实现简单 API 的仓库由其基本 URL 定义，这是所有附加 URL 所在的最顶级 URL。由于 PyPI 的基本 URL 是 https://pypi.ac.cn/simple/，该 API 被命名为“简单”仓库。

注意

本文档中所有后续 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="&gt;=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

最后修改：2025-08-20 21:30:45 GMT