文件下架¶

注意

本规范最初定义于PEP 592。

注意

PEP 592 包括对 HTML 和 JSON 索引 API 的更改。这些更改记录在简单仓库 API 中的HTML - 项目详情和JSON - 项目详情下。

规范¶

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

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

下架属性一旦设置就不是不可变的，将来可能会被撤销（一旦撤销，也可以再次设置）。因此，API 用户必须能够应对已下架文件被“取消下架”（甚至再次下架）的情况。

对于用户来说，理想的体验是，一旦文件被下架，当一个人当前尝试直接安装一个下架文件时，它会像该文件已被删除一样失败。但是，当一个人在很久以前这样做，而现在计算机只是继续机械地按照原始顺序安装现在已下架的文件时，它的行为就好像它没有被下架一样。

如果选择约束可以通过非下架版本满足，安装程序必须忽略下架版本，并且可以拒绝使用下架版本，即使这意味着请求根本无法满足。实现应该选择遵循上述意图精神的策略，并防止对下架版本/文件产生“新”依赖。

这意味着什么取决于具体的安装程序，以决定如何最好地适应其安装程序的整体使用。但是，有两种建议的方法

下架文件始终被忽略，除非它们是唯一与使用 ==（不带任何使其成为范围的修饰符，例如 .*）或 === 准确版本“固定”的版本说明符匹配的文件。此版本说明符的匹配应根据版本说明符规范进行，例如本地版本、零填充等。
下架文件始终被忽略，除非它们是唯一与锁文件（例如 Pipfile.lock 或 poetry.lock）指定安装的内容匹配的文件。在这种情况下，从某个输入文件或命令创建或更新锁文件时，不应使用下架文件。

无论安装程序选择何种策略来决定何时安装下架文件，安装程序在决定安装下架文件时应该发出警告。该警告可以利用 data-yanked 属性的值（如果它有值）向用户提供关于该文件为何被下架的更具体反馈。

镜像通常可以以两种方式处理下架文件

镜像不得在未同时镜像其 data-yanked 属性的情况下镜像下架文件。