核心元数据规范#
在以下规范中定义的字段应被视为有效、完整且不会更改。必需的字段为
Metadata-VersionNameVersion
所有其他字段都是可选的。
元数据（包括 wheels 和 已安装项目 中的元数据）的标准文件格式基于电子邮件头的格式。但是，电子邮件格式已经多次修订，并且不指定哪个电子邮件 RFC 适用于打包元数据。在没有明确定义的情况下，实际标准由标准库 email.parser 模块使用 compat32 策略解析的内容来设置。
每当元数据序列化为字节流（例如，保存到文件）时，都必须使用 UTF-8 编码序列化字符串。
虽然 PEP 566 定义了一种将元数据转换为 JSON 兼容词典的方法，但这尚未用作标准交换格式。由于需要使用工具来处理多年的现有软件包，因此很难转换到新格式。
注意
解释旧元数据： 在 PEP 566 中，版本说明符字段格式规范被放宽，以接受流行发布工具使用的语法（即删除版本说明符必须用括号括起来的要求）。元数据使用者可能希望对标称版本低于 2.1 的元数据文件也使用更宽松的格式化规则。
Metadata-Version#
版本 1.0 中的新增功能。
文件格式的版本；合法值为“1.0”、“1.1”、“1.2”、“2.1”、“2.2”和“2.3”。
使用元数据的自动化工具应在 metadata_version 大于它们支持的最高版本时发出警告，并且如果 metadata_version 的主版本号大于它们支持的最高版本，则必须失败（如 版本说明符规范 中所述，主版本号是第一个点之前的那个值）。
为了更广泛的兼容性，构建工具可以选择使用包含所有必需字段的最低元数据版本来生成发行版元数据。
示例
Metadata-Version: 2.3
Name#
版本 1.0 中的新增功能。
版本 2.1 中更改：从 名称格式 中添加了对格式的限制。
发行版的名称。名称字段是发行版的主要标识符。它必须符合 名称格式规范。
示例
Name: BeagleVote
出于比较目的，名称应在比较之前 标准化。
Version#
版本 1.0 中的新增功能。
包含发行版版本号的字符串。此字段必须采用 版本说明符规范 中指定的形式。
示例
Version: 1.0a2
动态（多用途）#
版本 2.2 中的新增功能。
包含另一个核心元数据字段名称的字符串。字段名称 Name、Version 和 Metadata-Version 无法在此字段中指定。
在源发行版的元数据中找到时，将应用以下规则
如果某个字段未标记为
Dynamic，则从 sdist 构建的任何轮子中的字段值必须与 sdist 中的值匹配。如果该字段不在 sdist 中，并且未标记为Dynamic，则它不得出现在轮子中。如果某个字段标记为
Dynamic，则它可能包含从 sdist 构建的轮子中的任何有效值（包括根本不存在）。
如果 sdist 元数据版本低于 2.2，则应将所有字段视为使用 Dynamic 指定的字段（即，对从 sdist 构建的轮子的元数据没有任何特殊限制）。
在源发行版之外的任何上下文中，Dynamic 仅供参考，并表示字段值是在轮子构建时计算的，可能与 sdist 中的值或项目中其他轮子中的值不同。
有关 Dynamic 语义的完整详细信息在 PEP 643 中进行了描述。
平台（多用途）#
版本 1.0 中的新增功能。
平台规范，描述发行版支持的操作系统，该操作系统未在“操作系统”Trove 分类器中列出。请参见下面的“分类器”。
示例
Platform: ObscureUnix
Platform: RareDOS
支持的平台（多用途）#
版本 1.1 中的新增功能。
包含 PKG-INFO 文件的二进制发行版将在其元数据中使用 Supported-Platform 字段来指定编译二进制发行版的操作系统和 CPU。此 PEP 中未指定 Supported-Platform 字段的语义。
示例
Supported-Platform: RedHat 7.2
Supported-Platform: i386-win32-2791
摘要#
版本 1.0 中的新增功能。
发行版用途的一行摘要。
示例
Summary: A module for collecting votes from beagles.
说明#
版本 1.0 中的新增功能。
版本 2.1 中已更改： 此字段也可以在邮件正文中指定。
发行版的较长说明，可以包含多个段落。处理元数据的软件不应假设此字段有任何最大大小，但人们不应将他们的操作手册作为说明包括在内。
此字段的内容可以使用 reStructuredText 标记编写 [1]。对于使用元数据的程序，支持标记是可选的；程序还可以按原样显示字段的内容。这意味着作者在使用的标记中应保持保守。
为了支持空行和相对于 RFC 822 格式缩进的行，任何 CRLF 字符都必须后跟 7 个空格，然后是管道 (“|”) 字符。因此，Description 字段被编码为折叠字段，可以由 RFC822 解析器解释 [2]。
示例
Description: This project provides powerful math functions
|For example, you can use `sum()` to sum numbers:
|
|Example::
|
| >>> sum(1, 2)
| 3
|
此编码意味着当使用 RFC822 读取器展开字段时，任何 CRLF 后跟 7 个空格和管道字符的出现都必须替换为单个 CRLF。
或者，发行版的说明也可以在邮件正文中提供（即，在标题后完全空行后，无需缩进或其他特殊格式）。
Description-Content-Type#
版本 2.1 中的新增功能。
一个字符串，说明发行版说明中使用的标记语法（如果有），以便工具可以智能地呈现说明。
历史上，PyPI 支持纯文本和 reStructuredText (reST) 中的说明，并且可以将 reST 呈现为 HTML。但是，发行版作者通常使用 Markdown (RFC 7763) 编写说明，因为许多代码托管网站呈现 Markdown README，并且作者会重复使用文件进行说明。PyPI 无法识别该格式，因此无法正确呈现说明。当 Markdown 保留为纯文本时，这导致 PyPI 上许多软件包的说明呈现不佳，或者更糟的是，尝试将其呈现为 reST。此字段允许发行版作者指定其说明的格式，从而为 PyPI 和其他工具打开呈现 Markdown 和其他格式的可能性。
此字段的格式与 HTTP 中的 Content-Type 头相同（即：RFC 1341）。简而言之，这意味着它有一个 type/subtype 部分，然后可以根据需要添加一些参数
格式
Description-Content-Type: <type>/<subtype>; charset=<charset>[; <param_name>=<param value> ...]
type/subtype 部分只有几个合法值
text/plaintext/x-rsttext/markdown
charset 参数可用于指定描述的字符编码。唯一的合法值是 UTF-8。如果省略，则假定为 UTF-8。
其他参数可能特定于所选子类型。例如，对于 markdown 子类型，有一个可选的 variant 参数，允许指定正在使用的 Markdown 变体（如果未指定，则默认为 GFM）。目前，识别出两种变体
GFM表示 GitHub 风味的 MarkdownCommonMark表示 CommonMark
示例
Description-Content-Type: text/plain; charset=UTF-8
示例
Description-Content-Type: text/x-rst; charset=UTF-8
示例
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
示例
Description-Content-Type: text/markdown
如果未指定 Description-Content-Type，则应用程序应尝试将其呈现为 text/x-rst; charset=UTF-8，如果它不是有效的 rst，则回退到 text/plain。
如果 Description-Content-Type 是一个无法识别的值，则假定的内容类型为 text/plain（尽管 PyPI 可能拒绝任何具有无法识别的值的内容）。
如果 Description-Content-Type 为 text/markdown，并且未指定 variant 或将其设置为无法识别的值，则假定的 variant 为 GFM。
因此，对于上面最后一个示例， charset 默认为 UTF-8， variant 默认为 GFM，因此它等效于之前的示例。
关键字#
版本 1.0 中的新增功能。
一个附加关键字列表，用逗号分隔，用于帮助在较大的目录中搜索发行版。
示例
Keywords: dog,puppy,voting,election
注意
此规范以前显示用空格分隔的关键字，但 distutils 和 setuptools 使用逗号对其进行了实现。这些工具已广泛使用多年，因此更容易更新规范以匹配事实标准。
主页#
版本 1.0 中的新增功能。
一个包含发行版主页 URL 的字符串。
示例
Home-page: http://www.example.com/~cschultz/bvote/
下载 URL#
版本 1.1 中的新增功能。
一个包含可以从中下载此发行版版本的 URL 的字符串。（这意味着 URL 不能类似于“…/BeagleVote-latest.tgz”，而必须是“…/BeagleVote-0.45.tgz”。）
维护者#
1.2 版中的新增功能。
一个至少包含维护者姓名字符串；可以提供其他联系信息。
请注意，此字段旨在用于项目由原始作者以外的人维护的情况：如果它与 Author 相同，则应省略它。
示例
Maintainer: C. Schultz, Universal Features Syndicate,
Los Angeles, CA <cschultz@peanuts.example.com>
维护者电子邮件#
1.2 版中的新增功能。
包含维护者电子邮件地址的字符串。它可以在 RFC-822 From: 头的合法形式中包含名称和电子邮件地址。
请注意，此字段适用于项目由非原始作者维护时使用：如果它与 Author-email 相同，则应省略它。
示例
Maintainer-email: "C. Schultz" <cschultz@example.com>
根据 RFC-822，此字段可以包含多个用逗号分隔的电子邮件地址
Maintainer-email: cschultz@example.com, snoopy@peanuts.com
许可证#
版本 1.0 中的新增功能。
指示许可证的文本，其中许可证不是“许可证”Trove 分类器的选择。请参见下面的 “分类器”。此字段还可用于指定通过 Classifier 字段命名的许可证的特定版本，或指示此类许可证的变体或例外情况。
示例
License: This software may only be obtained by sending the
author a postcard, and then the user promises not
to redistribute it.
License: GPL version 3, excluding DRM provisions
分类器（多用途）#
版本 1.1 中的新增功能。
每个条目都是一个字符串，为发行版提供单个分类值。分类器在 PEP 301 中进行了描述，Python 包索引发布了 当前定义的分类器 的动态列表。
此字段后面可以是分号后的环境标记。
示例
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console (Text Based)
Requires-Dist（多用途）#
1.2 版中的新增功能。
在 2.1 版中更改：字段格式规范已放宽，以接受流行发布工具使用的语法。
每个条目都包含一个字符串，其中命名了此发行版所需的另一个 distutils 项目。
需求字符串的格式包含一到四部分
项目名称，格式与
Name:字段相同。唯一强制部分。以逗号分隔的“额外”名称列表。这些名称由所需项目定义，指的是可能需要额外依赖项的特定功能。名称必须符合
Provides-Extra:字段指定的限制。版本说明符。解析格式的工具应接受其周围的可选括号，但生成它的工具不应使用括号。
分号后的环境标记。这意味着仅在指定条件下才需要该要求。
有关允许格式的完整详细信息，请参见 PEP 508。
项目名称应对应于 Python 包索引 上找到的名称。
版本说明符必须遵循 版本说明符 中描述的规则。
示例
Requires-Dist: pkginfo
Requires-Dist: PasteDeploy
Requires-Dist: zope.interface (>3.5.0)
Requires-Dist: pywin32 >1.0; sys_platform == 'win32'
Requires-Python#
1.2 版中的新增功能。
此字段指定发行版兼容的 Python 版本。安装工具在选择要安装的项目版本时可能会查看此字段。
值必须采用 版本说明符 中指定的格式。
例如，如果发行版使用 f 字符串，则可以通过指定以下内容来阻止在 Python < 3.6 上安装
Requires-Python: >=3.6
此字段后面不能跟随环境标记。
Requires-External（多用途）#
1.2 版中的新增功能。
在 2.1 版中更改：字段格式规范已放宽，以接受流行发布工具使用的语法。
每个条目都包含一个字符串，描述了发行版要使用的系统中的一些依赖项。此字段旨在作为对下游项目维护者的提示，并且对 distutils 发行版没有有意义的语义。
需求字符串的格式是外部依赖项的名称，后面可以是括号中的版本声明。
此字段后面可以是分号后的环境标记。
由于它们引用非 Python 软件版本，因此此字段的版本号不需要符合版本说明符规范中指定的格式：它们应对应于外部依赖项使用的版本方案。
请注意，对于要使用的字符串没有特定规则。
示例
Requires-External: C
Requires-External: libpng (>=1.5)
Requires-External: make; sys_platform != "win32"
Project-URL（多用途）#
1.2 版中的新增功能。
一个字符串，其中包含一个可浏览的项目 URL 和一个标签，它们用逗号分隔。
示例
Project-URL: Bug Tracker, http://bitbucket.org/tarek/distribute/issues/
标签是限制为 32 个字符的自由文本。
Provides-Extra（多用途）#
版本 2.1 中的新增功能。
在版本 2.3 中更改：PEP 685 限制有效值，使其明确（即不需要规范化）。对于较旧的元数据版本，值限制已与Name: 保持一致，并引入了规范化规则。
一个字符串，其中包含一个可选功能的名称。有效名称仅包含小写 ASCII 字母、ASCII 数字和连字符。它必须以字母或数字开头和结尾。连字符后面不能再跟连字符。名称仅限于与以下正则表达式匹配的名称（这保证了明确性）
^[a-z0-9]+(-[a-z0-9]+)*$
指定的名称可用于使依赖项有条件地取决于是否已请求可选功能。
示例
Provides-Extra: pdf
Requires-Dist: reportlab; extra == 'pdf'
第二个发行版需要一个可选依赖项，方法是将其放在方括号内，并且可以通过用逗号 (,) 分隔多个功能来请求多个功能。针对每个请求的功能评估需求，并将其添加到发行版的需求集中。
示例
Requires-Dist: beaglevote[pdf]
Requires-Dist: libexample[test, doc]
两个功能名称test 和doc 被保留，分别标记运行自动化测试和生成文档所需的依赖项。
可以指定Provides-Extra:，而无需在任何Requires-Dist: 中引用它。
在为较旧的元数据版本编写数据时，在执行比较时，名称必须按照用于Name: 字段的相同规则进行规范化。编写元数据的工具如果两个Provides-Extra: 条目在规范化后会冲突，则必须引发错误。
在读取较旧元数据版本的数据时，如果此字段的值在较新的元数据版本中无效，则工具应发出警告。如果值按照任何核心元数据版本中Name: 的规则无效，则应向用户发出警告，并忽略该值以避免歧义。在读取较旧元数据版本中的无效名称时，工具可以选择引发错误。
很少使用的字段#
本节中的字段目前很少使用，因为它们的设计灵感来自 Linux 软件包管理系统中的类似机制，并且目前还不清楚工具应如何在PyPI等开放索引服务器的上下文中解释它们。
因此，流行的安装工具完全忽略它们，这意味着软件包发布者几乎没有动力去适当地设置它们。但是，它们保留在元数据规范中，因为它们在信息方面仍然可能有用，并且还可以与精选软件包存储库结合使用，用于其最初的预期目的。
Provides-Dist（多用途）#
1.2 版中的新增功能。
在 2.1 版中更改：字段格式规范已放宽，以接受流行发布工具使用的语法。
每个条目都包含一个字符串，其中命名了一个包含在此发行版中的 Distutils 项目。此字段必须包含Name 字段中标识的项目，后跟版本：名称（版本）。
一个发行版可能提供其他名称，例如，表示多个项目已捆绑在一起。例如，ZODB 项目的源发行版在历史上包含 transaction 项目，该项目现在作为一个单独的发行版提供。安装此类源发行版满足 ZODB 和 transaction 的要求。
一个发行版还可能提供一个“虚拟”项目名称，它不对应于任何单独发行的项目：此类名称可能用于表示一个抽象功能，该功能可以由多个项目之一提供。例如，多个项目可能为给定的 ORM 提供 RDBMS 绑定：每个项目可能声明它提供 ORM-bindings，允许其他项目仅依赖于安装其中最多一个项目。
可以提供版本声明，并且必须遵循 版本说明符 中描述的规则。如果没有指定发行版的版本号，则会隐含该版本号。
此字段后面可以是分号后的环境标记。
示例
Provides-Dist: OtherProject
Provides-Dist: AnotherProject (3.4)
Provides-Dist: virtual_package; python_version >= "3.4"
废弃发行版（多次使用）#
1.2 版中的新增功能。
在 2.1 版中更改：字段格式规范已放宽，以接受流行发布工具使用的语法。
每个条目都包含一个字符串，描述此发行版使之废弃的 distutils 项目的发行版，这意味着这两个项目不应同时安装。
可以提供版本声明。版本号必须采用 版本说明符 中指定的格式。
此字段后面可以是分号后的环境标记。
此字段最常见的用法是在项目名称发生更改的情况下，例如，Gorgon 2.3 被纳入 Torqued Python 1.0。在安装 Torqued Python 时，应删除 Gorgon 发行版。
示例
Obsoletes-Dist: Gorgon
Obsoletes-Dist: OtherProject (<3.0)
Obsoletes-Dist: Foo; os_name == "posix"
已弃用的字段#
要求#
版本 1.1 中的新增功能。
自 1.2 版起已弃用： 支持 Requires-Dist
每个条目都包含一个字符串，描述此软件包所需的某些其他模块或软件包。
需求字符串的格式与可用于 import 语句的模块或软件包名称的格式相同，在括号中可以跟一个版本声明（可选）。
版本声明是一系列条件运算符和版本号，用逗号分隔。条件运算符必须是“<”、“>””、“<=”、“>=”、“==”和“!=”之一。版本号必须采用 distutils.version.StrictVersion 类接受的格式：两个或三个点分隔的数字组件，末尾可以有一个“预发布”标记，该标记由字母“a”或“b”后跟一个数字组成。示例版本号为“1.0”、“2.3a2”、“1.3.99”，
可以指定任意数量的条件运算符，例如，字符串“>1.0, !=1.3.4, <2.0”是一个合法的版本声明。
以下所有内容都是可能的需要字符串：“rfc822”、“zlib (>=1.1.4)”、“zope”。
没有应该使用哪些字符串的规范列表；Python 社区可以自行选择标准。
示例
Requires: re
Requires: sys
Requires: zlib
Requires: xml.parsers.expat (>1.0)
Requires: psycopg
提供#
版本 1.1 中的新增功能。
自 1.2 版起已弃用： 支持 Provides-Dist
每个条目都包含一个字符串，描述安装后此软件包将提供的软件包或模块。这些字符串应与需求字段中使用的字符串匹配。可以提供版本声明（不带比较运算符）；如果没有指定软件包的版本号，则会隐含该版本号。
示例
Provides: xml
Provides: xml.utils
Provides: xml.utils.iso8601
Provides: xml.dom
Provides: xmltools (1.3)
废弃#
版本 1.1 中的新增功能。
自 1.2 版起已弃用： 支持 Obsoletes-Dist
每个条目都包含一个字符串，描述此软件包使之废弃的软件包或模块，这意味着这两个软件包不应同时安装。可以提供版本声明。
此字段最常见的用法是在软件包名称发生更改的情况下，例如，Gorgon 2.3 被纳入 Torqued Python 1.0。在安装 Torqued Python 时，应删除 Gorgon 软件包。
示例
Obsoletes: Gorgon
历史#
2001 年 3 月：核心元数据 1.0 通过 PEP 241 批准。
2003 年 4 月：核心元数据 1.1 通过 PEP 314 批准。
2010 年 2 月：核心元数据 1.2 通过 PEP 345 批准。
2018 年 2 月：核心元数据 2.1 通过 PEP 566 批准。
添加
Description-Content-Type和Provides-Extra。添加将元数据转换为 JSON 的规范方法。
限制
Name字段的语法。
2020 年 10 月：核心元数据 2.2 通过 PEP 643 批准。
添加
Dynamic字段。
2022 年 3 月：核心元数据 2.3 通过 PEP 685 批准。
限制要规范化的额外名称。