摘要

包解析是Python用户体验的关键部分，也是扩展Python核心功能的方式。包解析的体验在大多数情况下是理所当然的，直到有人遇到包安装程序做了他们不期望的事情。安装程序在处理多个索引时的行为已成为意外行为的常见来源。通过其无处不在的特性，pip长期以来定义了生态系统中其他工具的标准预期行为，但Python安装程序在处理多个索引方面正在出现分歧。这种分歧的核心在于是在解析分发之前合并索引内容，还是按顺序单独处理每个索引。pip在匹配分发之前合并所有索引，而uv在匹配一个索引上的分发之后才移动到下一个索引。每种方法都有优点和缺点。本PEP旨在描述这些行为，分别称为“版本优先级”和“索引优先级”，以便社区讨论和故障排除可以共享通用词汇，并且工具可以根据这些描述实现可预测的行为。

动机

Python包用户经常发现自己需要指定PyPI以外的索引或包源。外部索引存在的原因有很多

• PyPI上的文件大小/配额限制
• 实现变体，例如PyTorch中不同的GPU库构建
• 组织内部共享的包的本地构建
• 本地包具有远程依赖项的情况，用户希望优先使用本地包而不是远程依赖项，同时在需要时仍然回退到远程依赖项

在大多数这些情况下，完全放弃PyPI是不可取的。相反，用户通常希望PyPI仍然是包的来源，但优先级较低。不幸的是，pip当前的設計排除了这种优先级概念。一些Python安装程序工具已经开发了处理多个索引的替代方法，这些方法包含了表达索引优先级的机制，例如uv和PDM。

创新和定制的潜力令人兴奋，但它带来了进一步碎片化Python打包生态系统的风险，而这已被认为是Python的弱点之一。本PEP的动机是鼓励安装程序提供更多关于它们如何处理多个索引的洞察，并提供一个可以为更广泛社区通用的词汇。

规范

向后兼容性

本PEP不规定任何安装程序必须进行任何更改，因此只有当工具选择采用不同于其当前实现的索引行为时，才会引入兼容性问题。

本PEP的语言与现有工具（包括pip和uv）并不完全一致。本PEP的语言可以在本PEP审查期间更改，或者如果本PEP的语言受到青睐，其他项目可以遵守它。提议这些术语的唯一目标是创建一个核心的、通用的词汇，使用户更容易了解其他安装程序。

由于某些工具依赖于其中一种或另一种行为，因此可能会出现一些潜在问题，即为特定行为定制可用资源/包可能会损害依赖其他行为的用户的体验。

• 不同的索引可能具有不同的元数据。例如，不能假定索引“A”上的包“something”的元数据与索引“B”上的“something”具有相同的依赖项。这打破了版本优先级的基本假设，但索引优先级可以处理这种情况。当安装程序在搜索顺序中降级到较低优先级的索引时，这意味着从新索引刷新包元数据。这既是改进，也是复杂化。从复杂化的角度来看，缓存的元数据条目必须由包名称和索引URL同时作为键，而不仅仅是包名称。从潜在改进的角度来看，只要包的不同实现变体将其分发包分离到不同的索引中，它们就可以在依赖项方面有所不同。
• 使用索引优先级时，用户可能无法像预期那样获得更新，因为某些更高优先级的索引尚未更新/与PyPI同步以获取最新包。如果更高优先级的索引有有效候选包，则不会找到较新的包。这将需要详细说明，因为它与pip已建立的行为相悖。
• 通过增加索引优先级，安装程序将提高选择哪个索引的可预测性，索引主机可能会滥用此机制，以拥有内容不同的同名文件。在使用版本优先级时，这违反了关键的包互换性假设，并将导致混乱。索引优先级将更具可行性，但这种情况仍有很大的混淆潜力。开发支持安装程序识别这些混淆问题的工具将很有帮助。这些工具可以独立于安装程序进程运行，作为验证一组索引的合理性的一种手段。根据这些工具的时间成本，安装程序可以在其进程中运行它们。当然，用户可以自行承担风险忽略建议。

安全隐患

索引优先级为用户创建了一种明确指定其索引之间信任层次结构的机制。因此，它限制了依赖混淆攻击的可能性。PEP 708拒绝了索引优先级作为依赖混淆攻击的解决方案。本PEP请求重新考虑该拒绝，将索引优先级用于不同的目的。本PEP主要由支持实现变体的愿望驱动，这是另一个讨论的主题，希望能促成一个PEP。它与PEP 708并非互斥，也不建议撤销或取消PEP 708。它是针对我们如何允许用户在比“每次安装”更细粒度的级别上选择使用哪个索引的答案。

有关PEP 708拒绝索引优先级的更详细讨论，请参阅本PEP的discuss.python.org帖子。

如何教授此内容

一开始，目标并非改变pip或任何其他工具的默认优先级行为。最好的教学方式也许是观察留言板、GitHub问题跟踪器和聊天频道，留意索引优先级可以帮助解决的问题。有几项长期存在的讨论会是宣传这些概念的良好起点。这两种官方支持行为的主题需要文档，我们，本PEP的作者，将在本PEP的审查期间开发这些文档。这些文档可能包括对几个索引的添加，以及在安装程序之间交叉链接这些概念。至少，我们期望添加到PyPUG和pip的文档中。

安装程序宣传活跃行为非常重要，尤其是在错误消息中，这将为用户提供有关这些行为的资源。

uv 用户已经在使用索引优先级。uv 很好地记录了这种行为，但总是有可能提高该文档在命令行中的可发现性，而用户实际上会在命令行中遇到意外行为。

参考实现

uv 项目以其默认行为展示了索引优先级。但是，uv 是用 Rust 实现的，因此如果需要一个基于 Python 工具的参考实现，我们，本 PEP 的作者，将提供一个。对于 pip 来说，我们认为实施计划如下：

• 对于不使用--extra-index-url或--find-links的用户，将不会有任何变化，也不需要迁移。
• pip用户可以通过CLI和pip.conf中的新配置设置来选择索引优先级行为。本提案不建议将任何策略作为任何安装程序的默认策略。它只建议记录工具提供的策略。
• 为使用多个索引的任何 pip 操作启用额外的info级别输出。在此输出中，说明当前的策略设置，并简要概述隐含行为，以及指向描述不同选项的文档的链接
• 添加调试输出，详细识别每个步骤中使用的索引，包括文件在配置层次结构中的位置，以及它包含的位置（通过配置文件、环境变量或CLI标志）。
• 通过整个pip安装过程，跟踪哪个索引用于哪个包/分发。存储此信息，以便像pip freeze这样的工具可以使用它
• 补充PEP 751（锁文件）以捕获包/分发来源的索引

被拒绝的想法

• 告诉用户设置代理/镜像，例如devpi或Artifactory，如果存在本地文件则提供本地文件，如果本地文件不匹配则转发到另一个服务器（PyPI）

  这与本提案的行为非常接近，只是这种方法需要托管一些服务器，并且在某些环境中可能对用户不可访问或无法配置。同样重要的是要考虑到，对于运营自己的索引的组织（例如，为了克服 PyPI 大小限制），这并不能解决最终用户对--extra-index-url或代理/镜像的需求。也就是说，除非组织将 PyPI 作为一个整体进行代理/镜像，并让用户将其代理/镜像配置为唯一的索引，否则这种方法不会带来任何改进。

• 构建标签和/或本地版本指定符足够吗？

  构建标签和本地版本指定符将优先于没有这些标签和/或本地版本指定符的包。在一组包中，在PyPI以外的服务器上托管的具有这些附加内容的构建将优先于PyPI上的包，而PyPI很少使用构建标签，并且禁止本地版本指定符。当包提供者希望提供自己的本地覆盖时，例如为用户提供优化构建的HPC维护者，这种方法是可行的。在某些方面，它的可行性较低，例如构建标签不会出现在pip freeze元数据中，以及PyPI上不允许本地版本指定符。构建和维护具有本地构建标签变体的包集合也需要大量工作。

  https://discuss.python.org/t/dependency-notation-including-the-index-url/5659/21

• 那PEP 708呢？这还不够吗？

  PEP 708专门旨在解决依赖混淆攻击，并未解决索引之间实现变体的可能性。它是一种过滤外部URL并将外部索引的允许列表编码到索引元数据中的方法。它不改变当前渠道之间缺乏优先级或偏好。

• 命名空间

  命名空间是一种指定包的方式，其中包的Python使用方式不变，但包安装会限制包的来源。PEP 752最近提出了一种通过保留前缀作为分组元素来在扁平包命名空间（例如PyPI）中多路复用包所有者的方法。NPM的“范围”概念也被提出作为这种可能性的一种很好的例子。本PEP不同之处在于，它针对的是多个索引，而不是扁平包命名空间。就可预测地选择特定包源而言，最终效果大致相同，只是命名空间方法更依赖于使用这些命名空间前缀来命名包，而本PEP则不那么细粒度，它会从用户指定的任何更高优先级的索引中拉取包。命名空间方法依赖于所有已配置的索引以类似方式处理给定命名空间，这留下了通常的担忧，即并非所有已配置的索引都同样受到信任。命名空间思想与本PEP并不冲突，但它也没有像本PEP那样改进索引信任的表达。

未解决的问题

[仍在决定/讨论中的任何观点。]

致谢

这项工作得到了NVIDIA的资助，通过聘用作者。NVIDIA的同事们通过他们的投入极大地改进了本PEP。Astral Software开创了索引优先级的行为，从而为本文奠定了基础。pip的作者们值得高度赞扬，感谢他们对版本优先级行为的始终如一的指导和耐心的沟通，尤其是在面临有争议的安全问题时。

版权

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