进阶 docs.pypi.org 2026-10-20 06:39:13 · 24 阅读

第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

可以看到,它只是重定向到了规范文件地址。

评论 (0)