第24章 PyPI 章节导读
简介
PyPI 提供了多个 API 端点和公开数据集,本章节的目录中对它们都有相应说明。
API 政策
使用 PyPI API 时,请注意以下政策。
缓存
所有 API 请求都会被缓存。对 JSON、RSS 和 Index API 的请求由我们的 CDN 服务商缓存。你可以通过响应中的 X-Cache 和 X-Cache-Hits 头判断请求是否命中缓存。
JSON、RSS 和 Index API 的响应中还包含 ETag 头。如果你需要频繁发送重复请求,请确保你的 API 客户端会遵守该头,据此决定是否真的重新发起请求。
XML-RPC API 无法标识缓存响应。
速率限制
由于大量使用了缓存和 CDN,PyPI API 目前在边缘层没有速率限制。但如果 XML-RPC API 的使用导致服务质量下降,可能会对其施加速率限制。
此外,对于不负责任的使用行为,PyPI 保留暂时或永久封禁对方的权利。
如果你计划向 PyPI API 发送大量请求,请遵守以下建议:
-
在客户端的
User-Agent头中设置唯一标识,最好附上你的联系方式。 -
尽量避免在短时间内(几分钟内)发送大量请求(上千次)。PyPI 通常能承受,但如有可能,建议把请求分散在更长的时间内串行发送。
-
如果你的客户端实际上是某个组织或服务,需要从 PyPI 下载大量软件包,请考虑搭建自己的索引镜像或缓存。
API 使用偏好
如需定期检查新包或已有包的更新,请使用我们的 RSS 订阅源。
不要再开发基于 XML-RPC API 的新集成,这些接口已计划弃用。现有的使用者应迁移到 JSON/RSS/Index API。
集成指南
许多工具已经与 PyPI 集成,用于上传软件包或获取数据;参见 Python Packaging Guide 中的工具推荐。
查询 PyPI 获取软件包 URL
从 https://pypi.org 复制下载链接时,你会得到一个包含随机哈希值的 URL。
这个哈希值由文件的校验和计算得出。PyPI 上单个文件的 URL 是静态的,不会变化。
官方建议
查询 PyPI 的 Index API 或 JSON API 来确定文件的下载地址。
可预测的 URL
在无法或不便使用 API 的场景下,可以使用我们的 conveyor 服务来获取文件。例如 Linux 软件包维护者就属于这种情况,因为构建脚本或软件包元数据有时要求使用静态 URL。
URL 可以按如下方式构造,wheel 文件名遵循 PEP 491 的命名规范。
host = "https://files.pythonhosted.org"
def source_url(name, version):
return f"{host}/packages/source/{name[0]}/{name}/{name}-{version}.tar.gz"
def wheel_url(name, version, build_tag, python_tag, abi_tag, platform_tag):
# https://www.python.org/dev/peps/pep-0491/#file-name-convention
wheel_parts = {
tag: re.sub(r"[^\w\d.]+", "_", part, re.UNICODE)
for tag, part in locals().items()
}
wheel_parts["optional_build_tag"] = (
f"-{wheel_parts['build_tag']}" if build_tag else ""
)
filename = "{name}-{version}{optional_build_tag}-{python_tag}-{abi_tag}-{platform_tag}.whl".format_map(
wheel_parts
)
return f"{host}/packages/{python_tag}/{name[0]}/{name}/{filename}"
使用可预测 URL 的示例:
$ curl -I https://files.pythonhosted.org/packages/source/v/virtualenv/virtualenv-15.2.0.tar.gz
HTTP/2 302
location: https://files.pythonhosted.org/packages/b1/72/2d70c5a1de409ceb3a27ff2ec007ecdd5cc52239e7c74990e32af57affe9/virtualenv-15.2.0.tar.gz
可以看到,它只是重定向到了规范文件地址。