PEP 566 – Python 软件包元数据 2.1
- 作者:
- Dustin Ingram <di at python.org>
- BDFL 委托：
- Daniel Holth
- 讨论至:
- Distutils-SIG 邮件列表
- 状态:
- 最终版
- 类型:
- 标准跟踪
- 主题:
- 打包
- 创建日期:
- 2017年12月1日
- Python 版本:
- 3.x
- 发布历史:
- 取代:
- 345
- 决议:
- Distutils-SIG 消息
摘要
本 PEP 描述了 Python 软件包核心元数据规范 1.2 版和 2.1 版之间的更改。1.2 版在 PEP 345 中指定。
它还将字段规范的规范来源更改为 核心元数据规范 参考文档，其中包含了字段名称及其语义和用法的具体细节。
字段
所有受支持的元数据字段的名称和语义的权威来源是 核心元数据规范 文档。
标有“(多次使用)”的字段可以在单个 PKG-INFO 文件中多次指定。其他字段在 PKG-INFO 文件中只能出现一次。标有“(可选)”的字段在有效的 PKG-INFO 文件中不是必需的；所有其他字段都必须存在。
2.1 版新增内容
Description-Content-Type (可选)
一个字符串，说明了分发包描述中使用的标记语法（如果有），以便工具能够智能地渲染描述。
历史上，像 PyPI 这样的工具假设包的描述是使用 reStructuredText (reST) 格式化的，如果描述不是有效的 reST，则会回退到纯文本。
引入此字段允许 PyPI 支持其他类型的标记语法，而无需做出此假设。
此字段的完整规范在 核心元数据规范 中定义。
Provides-Extra (可选，多次使用)
一个字符串，包含可选功能的名称。必须是有效的 Python 标识符。可用于根据是否已请求可选功能来使依赖关系成为条件。
引入此字段允许包安装工具（例如 pip）确定给定包提供了哪些额外功能，以便包发布工具（例如 twine）可以检查使用额外功能的 环境标记 是否存在问题。
此字段的完整规范在 核心元数据规范 中定义。
2.1 版更改内容
名称
此字段格式的规范现在与 PEP 508 中定义的分发名称规范相同。
描述
除了 Description 标题字段外，分发包的描述也可以在消息正文中提供（即，在标题后面有一个完全空白的行之后，无需缩进或其他特殊格式）。
版本说明符
版本编号要求以及指定版本之间比较的语义在 PEP 440 中定义。如 PEP 440 中定义的直接引用也允许作为版本说明符的替代。
遵循 PEP 508，版本说明符不再需要在 Requires-Dist、Provides-Dist、Obsoletes-Dist 或 Requires-External 字段中用括号括起来，例如 requests >= 2.8.1 现在是一个有效值。推荐的格式是不带括号，但解析元数据的工具也应该能够处理括号中的版本说明符。此外，公共索引服务器 可以 禁止这些字段中的严格版本匹配子句或直接引用。
版本说明符的使用方式与 PEP 345 保持不变。
环境标记
一个 环境标记 是一个可以在字段末尾、分号 (“;”) 之后添加的标记，用于添加有关执行环境的条件。
用于声明此类条件的环境标记格式在 PEP 508 的环境标记部分中定义。
环境标记的使用方式与 PEP 345 保持不变。
JSON 兼容元数据
可能需要将元数据存储在不允许有多个重复键的数据结构中，例如 JSON。
将元数据字段转换为此类数据结构的规范方法如下
- 应使用
email.parser.HeaderParser读取原始键值格式； - 所有转换后的键都应转换为小写。连字符应替换为下划线，但其他所有字符应保留；
- 任何标有“(多次使用)”字段的转换值应为包含给定键所有原始值的单个列表；
Keywords字段应通过逗号分隔原始值转换为列表；- 消息正文（如果存在）应设置为
description键的值。 - 结果应存储为以字符串为键的字典。
与 PEP 345 的差异摘要
参考资料
本文档指定元数据格式的 2.1 版本。1.0 版本在 PEP 241 中指定。1.1 版本在 PEP 314 中指定。1.2 版本在 PEP 345 中指定。2.0 版本虽然未正式接受，但在 PEP 426 中指定。
版权
本文档已置于公共领域。
致谢
感谢 Alyssa Coghlan 和 Thomas Kluyver 对本 PEP 的贡献。
来源: https://github.com/python/peps/blob/main/peps/pep-0566.rst
最后修改: 2025-02-01 08:55:40 GMT