元数据中知名项目URL¶

重要提示

本文档主要面向元数据消费者，他们应使用下文的规范化规则和知名列表，以确保整个Python生态系统中项目URL的呈现方式一致。

元数据生产者（如构建工具和独立包维护者）可继续使用他们喜欢的任何标签，只要在整体Project-URL长度限制之内。但是，在可能的情况下，鼓励用户选择能够规范化为知名标签的有意义的标签。

注意

有关在包的元数据中选择项目URL标签的用户指导，请参阅编写pyproject.toml - URL。

注意

本规范最初定义于PEP 753。

PEP 753废弃了Home-page和Download-URL元数据字段，转而使用Project-URL (多用途)，并定义了一个规范化和查找过程，以确定Project-URL是否“知名”，即是否具有分配给Home-page、Download-URL或其他常见项目URL的语义。

这允许索引（如Python包索引）和其他下游元数据消费者以一致的方式呈现项目URL。

标签规范化¶

注意

标签规范化由元数据消费者执行，而非元数据生产者。

为了确定Project-URL标签是否“知名”，元数据消费者应在将其与知名标签列表进行比较之前规范化该标签。

Project-URL标签的规范化过程由以下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`
`github`	`github`

知名标签¶

注意

知名标签列表是一个活标准，作为本文档的一部分进行维护。

下表列出了为专门呈现Project-URL元数据而知名的标签

标签（人类可读的等效项）	Description	别名
`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`

包元数据消费者可以选择将别名标签渲染为其“父”知名标签相同，或进一步特化它们。

示例行为¶

以下展示了项目URL元数据从pyproject.toml到核心元数据，再到潜在索引呈现的流程

标准配置中的项目URL示例¶

[project.urls]
"Home Page" = "https://example.com"
DOCUMENTATION = "https://readthedocs.org"
Repository = "https://upstream.example.com/me/spam.git"
GitHub = "https://github.com/example/spam"

核心元数据表示¶

Project-URL: Home page, https://example.com
Project-URL: DOCUMENTATION, https://readthedocs.org
Project-URL: Repository, https://upstream.example.com/me/spam.git
Project-URL: GitHub, https://github.com/example/spam

潜在渲染¶

Homepage: https://example.com
Documentation: https://readthedocs.org
Source Code: https://upstream.example.com/me/spam.git
Source Code (GitHub): https://github.com/example/spam

请注意，核心元数据以用户提供的形式出现（因为元数据生产者不执行规范化），但元数据消费者根据规范化形式进行规范化并识别适当的人类可读等效项

Home page变为homepage，渲染为Homepage
DOCUMENTATION变为documentation，渲染为Documentation
Repository变为repository，渲染为Source Code
GitHub变为github，渲染为Source Code (GitHub)（作为Source Code的特化）