摘要

此 PEP 提出了一种机制，允许托管在 pypi.org 上的项目在 PyPI 以外的外部网站上安全地托管 wheel 构件。此 PEP 明确不提议托管项目、包或其元数据。此功能已通过外部托管独立包索引可用。由于此 PEP 仅提供项目自定义特定已发布 wheel 构件下载 URL 的机制，因此像 pip 和 uv 等常见安装工具已实现的依赖项解析无需更改。

此 PEP 定义了在此上下文中“安全”的含义，以及一种名为 .rim 文件的新包上传文件格式。它定义了 .rim 文件如何影响包的 Simple Repository API 在 HTML 和 JSON 格式下的元数据，以及传统 Wheel 如何轻松转换为 .rim 文件。

PEP 已撤销

此 PEP 已由作者于 2025 年 1 月 31 日撤销。我们对讨论串中的情绪的理解是，尽管此 PEP 试图解决的问题是有效的，但大多数人会倾向于不同的方法。具体来说，我们认为大多数用户更希望能够更好地控制指定多个索引、这些索引如何互操作以及这些索引的优先级和信任断言。例如，像 PEP 766 这样的解决方案可能提供了更好的前进方向。现有的临时措施（例如 PyPI 限制增加请求和 “wheel-stub” 方法）在间歇期内已经足够（即使不是理想的）。作者感谢所有为建设性讨论做出贡献的人，特别是那些公开和私下表示支持此 PEP 的人。

基本原理

Python 包索引，托管在 https://pypi.ac.cn，对上传构件文件大小（100 MiB）和总项目大小（10 GiB）施加了 默认限制。大多数项目在项目生命周期内，通过多年的上传，都可以舒适地保持在这些限制内。少数项目遇到了这些限制，并获得了文件大小和项目大小的例外，允许它们继续上传新版本，而无需采取更极端的措施，例如删除可能仍在使用中的文件（例如通过版本固定）。

一个相关的解决方案是 “wheel stub” 方法，它提供了 PyPI 和外部第三方包索引之间的间接链接，在那里可以避免此类限制。Wheel stubs 是 源发行版（也称为“sdists”），它使用 PEP 517 构建后端，该后端不将源代码转换为二进制 wheel，而是执行一些逻辑来计算现有、外部托管 wheel 的 URL 以下载和安装。这种方法有效，但它模糊了 PyPI、sdist 和外部托管 wheel 之间的联系，因为没有办法将此信息呈现给 pip 或其他此类工具。

规范

定义了一种新型可上传文件，称为“RIM”（即 .rim）或“远程可安装元数据”文件。该名称令人联想到去掉轮胎的 Wheel 的图像，并强调 .rim 文件很容易从 .whl 文件派生。将 .whl 转换为 .rim 的过程在下面概述。文件名格式与 Wheel 文件命名格式 规范完全匹配，只是 RIM 文件使用 .rim 后缀。这意味着用于区分 .whl 文件的所有标签也区分了不同的 .rim 文件，因此可以在依赖项解析步骤中像今天的 .whl 文件一样使用。在这方面，.whl 和 .rim 文件是可互换的。

一个 .rim 文件内容与 .whl 文件几乎相同，但 .rim 文件必须仅包含 Wheel 中的 .dist-info 目录。在 .rim zip 文件中不允许包含任何其他顶级文件或目录。 .dist-info 目录必须包含一个额外文件，除了允许在 .whl 文件的 .dist-info 目录中的文件之外：一个名为 EXTERNAL-HOSTING.json 的文件。

这是一个 JSON 文件，包含以下键

version

这是文件格式版本，对于此 PEP，必须为 1.0。

owner

此必须是此外部托管文件的 PyPI 组织所有者的名称，原因将在下文详细介绍。

uri

这是一个单一 URL，命名了托管在外部网站上的物理 .whl 文件的位置。此 URL必须使用 https 方案。

size

这是一个整数值，描述了远程主机上物理 .whl 文件的大小（以字节为单位）。

hashes

这是一个字典，格式如PEP 694中所述，用于捕获物理 .whl 文件的PEP 694，具有与该 PEP 中提出的相同约束。由于这些哈希值一旦上传到 PyPI 就不可变，因此它们作为关键验证，以确保外部托管的 wheel 没有损坏或被泄露。

外部托管的弹性

导致 PEP 438 在 PEP 470 中被撤销的关键顾虑之一是，当外部索引消失时，用户可能会感到困惑。来自 PEP 470

这种困惑在于项目最终用户没有意识到项目是托管在 PyPI 上还是依赖于外部服务。这通常在外部服务停止而 PyPI 没有停止时显现出来。人们会看到 PyPI 工作正常，其他项目也工作正常，但这个特定的项目不行。他们通常不知道他们需要联系谁来解决这个问题，或者他们的补救步骤是什么。

虽然此 PEP 没有直接解决外部 Wheel 托管服务停止运行的问题，但采取了几项保护措施，以大大减轻 PyPI 管理员的潜在负担。

因此，此 PEP 提议：

• 仅允许由组织账户拥有的包进行外部 Wheel 托管。外部托管是组织范围内的设置。
• 组织账户不会自动获得外部托管 Wheel 的能力；此功能必须由 PyPI 管理员酌情明确启用。由于这不是一个常见的请求，我们不认为其开销会像PEP 541 解决方案、账户恢复请求，甚至文件/项目大小增加请求那样繁重。外部托管请求将以与这些请求相同的方式处理，即通过 PyPI GitHub 支持跟踪器。
• 请求外部 Wheel 托管的组织账户必须注册自己的支持联系 URI，无论是用于联系电子邮件地址的 mailto URI，还是组织支持跟踪器的 URL。对于不使用外部 Wheel 文件托管的组织，此类联系 URI 是可选的。

结合 EXTERNAL-HOSTING.json 文件中的 owner 键，这使得安装工具能够明确地将任何下载错误从 PyPI 支持管理员重定向到组织的（支持）管理员。

虽然存储和检索此组织支持 URL 的确切机制将单独定义，但举例来说，假设一个名为 foo 的包在 `https://foo.example.com <https://foo.example.com>`__ 上外部托管 Wheel 文件，并且该主机变得不可达。当安装工具尝试下载和安装 foo 包的 Wheel 时，下载步骤将失败。然后，安装工具将能够查询 PyPI，向最终用户提供有用的错误消息

• 安装程序下载 .rim 文件，并读取 .rim zip 文件内的 EXTERNAL-HOSTING.json 文件中的 owner 键。
• 安装程序查询 PyPI 以获取外部托管 Wheel 的组织所有者的支持 URI。
• 然后将显示一条信息性错误消息，例如：

  无法下载外部托管的 Wheel 文件 foo-....whl。请联系 support@foo.example.com 获取帮助。请勿将此问题报告给 PyPI 管理员。

卸载 Wheel

通常很容易从现有的 .whl 文件生成 .rim 文件。这可以通过 PEP 518 构建后端附加命令行选项，或一个单独的工具来实现，该工具以 .whl 文件作为输入并创建相关的 .rim 文件。为了完成类比，将 .whl 转换为 .rim 的过程称为“卸载”。此类工具将执行的步骤是

• 接受源 .whl 文件、包的组织所有者、.whl 将要托管的 URL 以及用于报告下载问题的支持 URI 作为输入。这些实际上可以包含在 pyproject.toml 文件中，但这超出了本 PEP 的范围。
• 解压 .whl 并创建 .rim zip 存档。
• 从 .rim 文件中省略不以 .dist-info 目录为根的 .whl 中的任何路径。
• 计算源 .whl 文件的哈希值。
• 将包含上述 JSON 键和值的 EXTERNAL-HOSTING.json 文件添加到 .rim 存档中。

工具的更改

理论上，安装程序工具不需要任何更改，因为当它们识别出要下载和安装的 Wheel 时，它们只需查询 PyPI 的 Simple API 返回的下载 URL。但实际上，像 pip 和 uv 这样的工具可能对允许下载的托管服务器有限制，例如 PyPI 自带的 pythonhosted.org 域名。

在这种情况下，这些工具将需要放宽这些限制，但具体策略由安装程序工具自行决定。可以实现任何数量的方法，例如下载 .rim 文件并验证 EXTERNAL-HOSTING.json 元数据，或者简单地信任具有匹配校验和的 Wheel 的外部下载。它们还可以查询 PyPI 以获取项目的组织所有者和支持 URI，然后再信任下载。它们可以警告用户何时遇到外部托管的 Wheel 文件，和/或要求使用命令行选项来启用其他下载主机。任何这些验证策略都可以通过配置文件选择。

安装程序工具在外部托管的 Wheel 文件无法下载时（例如，因为主机不可达）可能还需要提供更好的错误消息。如上所述，这些工具可以从 PyPI 查询足够的元数据，以提供清晰且区别的错误消息，将用户指向包的外部托管支持电子邮件或问题跟踪器。

外部托管服务的约束

以下约束条件可确保可靠且兼容的外部 Wheel 托管服务

• 外部 Wheel必须通过 HTTPS 提供服务，并使用由 Mozilla 的根证书存储签名的证书。这确保了与 pip 和 uv 的兼容性。在撰写本文时，Python 3.10 或更高版本上的 pip 24.2 除了第三方 certifi Python 包提供的 Mozilla 存储外，还使用系统证书存储。 uv 使用 webpki-roots crate 提供的 Mozilla 存储，但不使用系统存储，除非提供了 --native-tls 标志 [1]。PyPI 管理员可能会在将来修改此要求，但与流行安装程序的兼容性不会受到损害。
• 外部 Wheel 主机应使用内容分发网络（CDN），就像 PyPI 一样。
• 外部 Wheel 主机必须承诺为其托管的所有 Wheel 提供稳定的 URL。
• 外部托管的 Wheel不得从外部 Wheel 主机中删除，除非相应的 .rim 文件首先从 PyPI 中删除，并且不得删除已撤销版本的外部 Wheel。
• 外部 Wheel 主机必须支持 HTTP Range 请求。
• 外部 Wheel 主机应支持 HTTP/2 协议。

安全

本提案中描述的几个因素应能缓解外部托管 Wheel 的安全问题，例如：

• Wheel 文件校验和必须包含在 .rim 文件中，并且一旦上传就无法更改。由于存储在 PyPI 上的校验和是不可变的且必需的，因此即使所有者组织失去了对其托管域的控制，也无法伪造外部 Wheel 文件。
• 外部托管的 Wheel必须通过 HTTPS 提供服务。
• 为了提供外部托管的 Wheel，组织必须获得 PyPI 管理员的批准。

当用户发现 PyPI 托管项目中的恶意软件或漏洞时，他们现在可以使用 PyPI 上的恶意软件报告工具，如本博客文章中所述。相同的流程可用于报告外部托管 Wheel 中的安全问题，并且应使用相同的补救流程。此外，由于启用了外部托管的组织必须提供支持联系 URI，因此在某些情况下可以使用该 URI 向托管组织报告安全问题。此类组织报告对于恶意软件可能没有意义，但对于报告外部托管 Wheel 中的安全漏洞来说，可能确实是一种非常有用的方式。

被拒绝的想法

已考虑并拒绝了几种想法。

• 要求对外部托管的 Wheel 文件进行数字签名，无论是附加的还是除哈希值之外的。我们认为这是不必要的，因为校验和要求应该足以验证 PyPI 上 Wheel 的元数据是否与下载的 Wheel 完全匹配。密钥管理的额外复杂性会抵消此类数字签名可能带来的任何额外好处。
• 对 .rim 文件上传进行哈希验证。PyPI可以在接受上传之前验证上传的 .rim 文件中的哈希值是否与外部托管的 Wheel 匹配，但这需要下载外部 Wheel 并执行校验和，这也意味着在下载和验证此外部 .whl 文件之前，无法接受 .rim 文件的上传。这会增加 PyPI 的带宽并减慢上传查询速度，尽管 PEP 694 草稿上传可能潜在地缓解了这些担忧。尽管如此，收益可能不值得额外的复杂性。
• 索引定期验证下载 URL。PyPI 可以尝试定期确保外部 Wheel 主机或外部 .whl 文件本身仍然可用，例如通过HTTP HEAD 请求。这可能是多余的，并且如果响应[2]中不包含文件的校验和，可能不会带来太多额外的好处。
• 此 PEP 允许组织提供备用下载主机，这样在主主机出现故障时，次级主机就可以使用。我们认为基于 DNS 的复制是一种更好、更广为人知且可能更具弹性的技术。
• .rim 文件替换。虽然允许 .whl 文件替换现有的 .rim 文件（只要 a) .rim 文件未被删除或撤销，b) 校验和匹配），但我们不允许用 .rim 文件替换 .whl 文件，也不允许 .rim 文件覆盖现有的 .rim 文件。后者可能是一种更改外部托管 .whl 的托管 URL 的技术；然而，我们认为这不是一个好主意。如上所述，“修复”外部主机 URL 有其他方法，我们不希望鼓励大规模重新上传现有的 .rim 文件。

脚注

版权

本文档置于公共领域或 CC0-1.0-Universal 许可证下，以更宽松者为准。