PEP 753 – 核心元数据中统一项目 URL

作者:: William Woodruff <william at yossarian.net>, Facundo Tuesca <facundo.tuesca at trailofbits.com>
发起人:: Barry Warsaw <barry at python.org>
PEP 代理人:: Paul Moore <p.f.moore at gmail.com>
讨论至:: Discourse 帖子
状态:: 已接受
类型:: 标准跟踪
主题:: 打包
创建日期:: 2024年8月29日
发布历史:: 2024年8月26日, 2024年9月3日
决议:: 2024年10月10日

摘要
原理与动机
规范
- 元数据生产者
- 包索引
Project-URL 标签约定
- 标签规范化
- 知名标签
向后兼容性
- 影响有限
未来考虑
安全隐患
如何教授
附录A：标签规范化示例
版权

重要

本PEP是一个历史文档。最新的规范《元数据中知名项目URL》在PyPA规范页面上维护。

有关如何提出更改的建议，请参阅PyPA 规范更新流程。

摘要

本PEP建议对索引（如PyPI）和其他核心元数据消费者处理核心元数据的方式进行两项离散的更改：

废弃 Home-page 和 Download-URL 字段，转而使用其 Project-URL 等效字段；
一套约定，用于在消费者端元数据处理期间对 Project-URL 标签进行规范化并赋予语义。

原理与动机

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

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

元数据 1.0 引入了 Home-page，这是一个单次使用的字段，包含指向分发主页的URL。
```
Home-page: https://example.com/sampleproject
```
元数据 1.1 引入了 Download-URL，这是一个补充性的单次使用的字段，包含适合下载当前分发的URL。
```
Download-URL: https://example.com/sampleproject/sampleproject-1.2.3.tar.gz
```

元数据 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）都具有影响。

元数据生产者

本PEP对元数据生产者规定如下：

当生成元数据 1.2 或更高版本时，生产者应该只发出 Project-URL，不应该发出 Home-page 或 Download-URL 字段。

这些规定并未改变核心元数据中URL字段的可选性。换句话说，生产者可以根据其酌情权选择完全省略 Project-URL。

本PEP不提议彻底取消对 Home-page 或 Download-URL 的支持。然而，有关新的（尚未明确的）主要核心元数据版本如何通过移除这些已弃用字段来完成弃用周期的思考，请参阅未来考虑。

同样，本PEP不建议元数据生产者发出规范化标签。标签规范化仅在处理和消费端（即在索引和其他分发元数据消费者中）执行。

包索引

本PEP对包索引规定如下：

当解释版本 1.2 或更高版本的分发元数据时（例如，在网页上渲染），索引必须优先使用 Project-URL 字段作为 URL 来源，而不是 Home-page 和 Download-URL，即使后者已明确提供。
如果一个分发的元数据只包含 Home-page 和 Download-URL 字段，索引可以选择忽略这些字段，并表现为元数据中未提供任何URL。在这种情况下，索引应该向上传方提供适当的警告或通知。
- 发出此警告或通知的机制未指定，因为它将因索引而异。举例来说，索引可以选择在上传请求的HTTP响应中显示警告，或者向项目维护者发送电子邮件或其他通知。
如果分发元数据同时包含两组字段，索引可以选择直接拒绝该分发。然而，在未来的未指定主要元数据版本正式移除对 Home-page 和 Download-URL 的支持之前，这不推荐。
对版本 1.2 或更高版本的元数据解释所做的任何更改，如果导致以前识别的URL不再被识别，则不应该追溯应用于以前上传的包。

这些规定并未改变索引处理URL的可选性。换句话说，一个不处理上传分发中URL的索引可以继续完全忽略所有URL字段。

同样，这些规定不意味着索引应保留其对分发元数据执行的任何规范化。换句话说，本PEP规定标签规范化的目的是为了用户展示，而不是为了修改已上传的分发或其“附加”PEP 658元数据文件。

`Project-URL` 标签约定

上述提议的弃用需要正式化 Home-page、Download-URL 及其 Project-URL 等效字段之间目前非正式的关系。

这种正式化分为两部分：

一套在索引端处理期间规范化 Project-URL 标签的规则；
一组“知名”的规范化标签值，索引可以为其专门化 URL 呈现方式。

标签规范化

核心元数据规范规定 Project-URL 标签是自由文本，限制为 32 个字符。

本PEP提议在核心元数据规范中添加“规范化”标签的概念。标签规范化通过以下Python函数定义：

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

简而言之：标签通过删除所有ASCII标点符号和空格，然后将结果转换为小写字母来规范化。

下表显示了规范化前（原始）和规范化后（规范化）的标签示例：

原始	规范化
`Homepage`	`homepage`
`Home-page`	`homepage`
`Home page`	`homepage`
`Change_Log`	`changelog`
`What's New?`	`whatsnew`

在处理分发元数据时，包索引应该执行标签规范化，以确定给定标签是否知名，以便进行后续的特殊处理。非知名的标签必须以其未规范化的形式进行处理。

规范化不改变关于重复 Project-URL 标签的现有语义。换句话说，规范化可能导致项目元数据中出现重复标签，但这仅以已允许的方式进行（因为核心元数据规范并未规定标签必须唯一）。

规范化元数据字段的摘录示例在附录A中提供。

知名标签

除了上述规范化规则外，本PEP还提议了一组固定（但可扩展）的“知名”Project-URL标签，以及别名和人类可读的等效项。

下表列出了这些规范化形式的标签：

标签（人类可读的等效项）	描述	别名
`homepage` (主页)	项目主页	（无）
`source` (源代码)	项目托管的源代码或存储库	`repository`, `sourcecode`, `github`
`download` (下载)	当前分发的下载URL，等同于 `Download-URL`	（无）
`changelog` (更新日志)	项目的综合更新日志	`changes`, `whatsnew`, `history`
`releasenotes` (发布说明)	项目的精选发布说明	（无）
`documentation` (文档)	项目的在线文档	`docs`
`issues` (问题跟踪)	项目的错误跟踪器	`bugs`, `issue`, `tracker`, `issuetracker`, `bugtracker`
`funding` (资助)	资助信息	`sponsor`, `donate`, `donation`

如果合适，索引可以选择在其UI元素中使用上述建议的人类可读等效项。或者，索引可以选择其自己的适当的人类可读等效项用于UI元素。

打包者和元数据生产者可以选择使用任何规范化为这些标签（或其别名）的标签，以向包索引和下游传递特定的URL意图。

同样，索引可以选择专门化这些标签的URL渲染或呈现方式，例如，为每个标签显示一个适当的图标或工具提示。

索引也可能对附加标签或URL的渲染或呈现进行特殊处理，包括（但不限于）以知名标签开头的标签，以及引用已知服务提供商域名的URL（例如，用于文档托管或问题跟踪）。

本PEP认识到知名标签列表不太可能保持静态，并且后续的添加不应需要与正式的PEP流程或新的元数据版本相关的开销。因此，本PEP提议将上述列表成为 PyPA 规范中的一个“活”列表。

向后兼容性

影响有限

本PEP预计对现有打包工具或包索引的影响微乎其微：

打包工具：核心元数据的正确性或格式良好性没有变化。本PEP提议了弃用和行为改进，但所有当前（和历史上）生成的元数据将继续根据其各自版本的规则保持有效。
包索引：索引将继续期望格式良好的核心元数据，行为上没有变化。索引可以选择在存在已弃用字段时发出警告或通知，如上所述。

未来考虑

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

然而，根据元数据生产者和Project-URL标签约定，我们确定了核心元数据标准新主要版本的以下潜在未来目标：

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

这些潜在的变化将向后不兼容，因此只包含在本节中。接受本PEP并不意味着未来的元数据修订实际会进行这些更改。

安全隐患

本PEP未发现与弃用 Home-page 和 Download-URL 或标签规范化相关的任何积极或消极安全隐患。

如何教授

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

少数包维护者可能会收到来自其所选索引的新警告或通知，如果该索引选择忽略 Home-page 和 Download-URL（如建议）。同样，少数包维护者可能会发现其所选索引不再渲染其URL，如果这些URL仅存在于已弃用的字段中。然而，由于本PEP提议的更改，任何包维护者都不应遇到被拒绝的包上传或其他破坏性的打包工作流程更改。

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

如果本PEP被接受，本PEP的作者将协调更新和交叉链接上述资源。

附录A：标签规范化示例

本附录提供了分发元数据在索引端处理前后的说明性摘录：

之前

Project-URL: Home-page, https://example.com
Project-URL: Homepage, https://another.example.com
Project-URL: Source, https://github.com/example/example
Project-URL: GitHub, https://github.com/example/example
Project-URL: Another Service, https://custom.example.com

之后

Project-URL: homepage, https://example.com
Project-URL: homepage, https://another.example.com
Project-URL: source, https://github.com/example/example
Project-URL: github, https://github.com/example/example
Project-URL: Another Service, https://custom.example.com

特别是，请注意：

规范化的重复项被保留（Home-page 和 Homepage 都变为 homepage）；
Source 和 GitHub 都被规范化为各自的形式，但 github 没有被转换为 source。
Another Service 未规范化，因为其规范形式（anotherservice）并非知名标签。

版权

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

来源: https://github.com/python/peps/blob/main/peps/pep-0753.rst

最后修改: 2024-10-30 06:11:26 GMT