摘要

本 PEP 建议对索引（如 PyPI）处理核心元数据的方式进行两处独立的更改

• 弃用 Home-page 和 Download-URL 字段，转而使用其 Project-URL 等价物；
• 一组用于规范化和为 Project-URL 标签分配语义的约定。

基本原理和动机

Python 的标准 核心元数据 经历了多年的修订，并具有各种标准化的里程碑版本。

这些核心元数据的修订引入了各种机制，用于通过 URL 表达包与外部资源的关系

1. 元数据 1.0 引入了 Home-page，这是一个单用途字段，包含指向发行版主页的 URL。

   Home-page: https://example.com/sampleproject
   

2. 元数据 1.1 引入了 Download-URL，这是一个补充性的单用途字段，包含适合下载当前发行的 URL。

   Download-URL: https://example.com/sampleproject/sampleproject-1.2.3.tar.gz
   

3. 元数据 1.2 引入了 Project-URL，这是一个多用途字段，包含标签和 URL 对。每个标签都是自由文本，传达 URL 的语义。

   Project-URL: Homepage, https://example.com/sampleproject
   Project-URL: Download, https://example.com/sampleproject/sampleproject-1.2.3.tar.gz
   Project-URL: Documentation, https://example.com/sampleproject/docs
   

元数据 2.1、2.2 和 2.3 将这些字段的行为保留为最初指定的。

因为 Project-URL 允许自由文本标签并且是多用途的，所以出现了用于在 Project-URL 中表示 Home-page 和 Download-URL 值的非正式约定。

这些约定得到了广泛采用，PEP 621 明确选择仅提供 project.urls 表格，而不是 project.home-page 字段。来自 PEP 621 的被拒绝的想法

虽然核心元数据支持它，但对于项目的 URL 使用单个字段，同时还支持完整的表格，这似乎是多余且令人困惑的。

本 PEP 的存在是为了将出现的非正式约定形式化，以及明确记录 Home-page 和 Download-URL 已被弃用，转而使用等效的 Project-URL 表示。

规范

本 PEP 提出将 Home-page 和 Download-URL 视为已弃用。此弃用对包元数据生产者（例如构建后端和打包工具）和包索引（例如 PyPI）都有影响。

Project-URL 标签约定

上述弃用需要正式确定 Home-page、Download-URL 及其 Project-URL 等价物之间当前非正式的关系。

此规范化包含两个部分

1. 一组用于规范化 Project-URL 标签的规则；
2. 一组索引可以专门用于 URL 展示的“知名”规范标签值。

import string
def canonicalize_label(label: str) -> str:
    chars_to_remove = string.punctuation + string.whitespace
    removal_map = str.maketrans("", "", chars_to_remove)
    return label.translate(removal_map).lower()

向后兼容性

未来考虑

此 PEP 并未规定或要求任何未来的元数据更改。

但是，根据元数据生成器和项目 URL 标签约定，我们确定了核心元数据标准的下一个主要版本的一些潜在未来目标。

• 在下一个主要核心元数据版本中完全移除对Home-page和Download-URL的支持。如果移除，软件包索引和使用者**必须**拒绝包含这些字段的元数据，当该元数据属于新的主要版本时。
• 强制实施标签规范化。如果强制实施，软件包生产者**必须**在生成发行版元数据时仅发出规范化的Project-URL标签，并且软件包索引和使用者**必须**拒绝包含非规范化标签的发行版。注意：要求规范化仅限于将标签限制为小写文本，并排除空格和标点符号。它**不**限制项目 URL 仅使用“知名”标签。

这些潜在的更改将是不兼容的，因此仅包含在本节中。接受此 PEP**不会**承诺任何未来的元数据修订实际上会进行这些更改。

安全隐患

此 PEP 未识别与弃用Home-page和Download-URL或与标签规范化相关的任何正面或负面的安全影响。

如何教授

此 PEP 中的更改对于打包生态系统的大多数用户来说应该是透明的；此 PEP 更改的主要受益者是打包工具作者和索引维护者，他们将能够减少生成和检查的唯一 URL 字段的数量。

少数软件包维护者可能会从其选择的索引中观察到新的警告或通知，如果该索引选择忽略Home-page和Download-URL（如建议的那样）。同样，少数软件包维护者可能会观察到其选择的索引不再呈现其 URL，如果仅存在于已弃用的字段中。但是，由于此 PEP 提出的更改，没有任何软件包维护者应该观察到被拒绝的软件包上传或打包工作流程的其他重大更改。

任何观察到索引上 URL 显示的警告或更改的人员都可以通过官方打包资源了解此 PEP 的行为，例如Python 打包用户指南和PyPI 的用户文档，后者已经包含了 PyPI 的 URL 处理行为的非正式描述。

如果此 PEP 被接受，此 PEP 的作者将协调更新和交叉链接上面提到的资源。

版权

本文档放置在公共领域或根据 CC0-1.0-Universal 许可证，以两者中更宽松者为准。