摘要

本 PEP 提案在简单仓库中添加标记特定文件下载为“yanked”的功能。Yanking 文件允许作者有效地删除文件，而不会影响那些已经固定到特定版本的用户的行为。

它还将简单仓库 API 的规范来源更改为 简单仓库 API 参考文档。

动机

每当一个项目发现 PyPI 上的特定版本可能存在问题时，他们通常希望阻止更多用户无意中使用该版本。然而，最明显的解决方案是删除仓库中的现有文件，这将影响那些遵循最佳实践并固定到特定项目版本的用户的行为。

这使得项目陷入困境，因为新项目可能会下载这个已知存在问题的版本，但如果他们采取任何措施来阻止这种情况，他们会影响到已经使用该版本的项目。

通过允许“yank”文件，但仍将其提供给明确要求它的用户，这使项目能够在最大程度上减少破坏性影响，同时仍然让那些已经解决问题或没有遇到底层问题的人正常使用。

可能发生这种情况的主要场景之一是当不再支持特定版本的 Python 时。 python-requires 元数据允许以不影响仍使用该 Python 版本的用户的方式放弃对 Python 版本的支持。但是，一个常见的错误是遗漏或忘记更新该元数据。当出现这种情况时，项目实际上只有三个选择

• 通过某种机制阻止该版本被安装（目前，唯一的方法是完全删除该版本）。
• 重新发布一个正常的版本，并使用更高的版本号，然后重新发布一个支持已被移除的版本，并使用更高的版本号，并附带正确的元数据。
• 不做任何操作，并说明使用较旧 Python 版本的用户必须手动排除该版本。

有了本 PEP，项目可以选择第一个选项，但使用一种不太可能影响到目前正在使用该项目的用户的机制。

规范

简单仓库中的链接 **可以** 包含一个 data-yanked 属性，该属性可以没有值，也可以包含任意字符串作为值。 data-yanked 属性的存在 **应该** 被解释为表示该链接指向的文件已被“Yanked”，并且通常不应被安装程序选择，除非在特定情况下。

data-yanked 属性的值（如果存在）是一个任意字符串，表示为什么该文件被 yanked 的原因。处理简单仓库 API 的工具 **可以** 将此字符串展示给最终用户。

一旦设置，yanked 属性不可变，可以在将来取消（取消后可以重新设置）。因此，API 用户 **必须** 能够应对一个 yanked 文件被“unyanked”（甚至再次 yanked）的情况。

被拒绝的想法

简单仓库 API 的一个先前未公开的版本包含特定于版本的页面，比如 /simple/<project>/<version>/。如果我们要添加这些页面，yanked 文件只能出现在这些页面上，而不能出现在无版本页面上。但这将大大降低简单 API 的可缓存性，并将直接影响我们扩展其规模以处理所有传入流量的能力。

本 PEP 的先前迭代将 data-yanked 属性作为布尔值。然而，人们决定允许使用字符串既简化了实现，又提供了额外的通用功能，允许项目提供一种机制来表明他们为什么在 yank 一个版本。

另一个建议是保留任意字符串中的某些语法，以便我们将来在需要时能够发展标准。然而，考虑到我们将来可以添加额外的属性，这个想法被拒绝了，而是倾向于在需要时使用额外的属性。

Warehouse/PyPI 实现笔记

虽然本 PEP 在文件级别实现了 yanking，但这很大程度上是由于简单仓库 API 的形式，而不是本 PEP 做出的特定决定。

在 Warehouse 中，用户体验将从 yank 或 unyank 整个版本的角度来实现，而不是作为对单个文件的操作，然后通过 API 作为单个文件被 yank 来公开。

其他仓库实现可以选择以不同的方式公开此功能，或者根本不公开它。

版权

本文件已进入公有领域。