摘要

本 PEP 描述了 setup.cfg 文件中一个新的部分和一种新的格式，它允许在不使用 setup.py 的情况下描述包的元数据。

拒绝通知

由于 distutils2 将不再被纳入标准库，因此此 PEP 于 2013 年 4 月底被 Alyssa Coghlan 拒绝。

将创建一个基于 PEP 426（元数据 2.0）的替换 PEP，它将定义生成 sdist 归档文件所需的最低信息量，前提是给定一个源代码压缩包或 VCS 检出。

基本原理

现在，如果您想列出未安装的发行版的元数据（参见 PEP 314），则需要使用 setup.py 命令行界面。

所以，基本上，您下载它，然后运行

$ python setup.py --name
Distribute

$ python setup.py --version
0.6.4

其中 name 和 version 是元数据字段。这工作得很好，但是一旦开发人员在 setup.py 中添加更多代码，此功能可能会失效，或者在最坏的情况下，可能会在目标系统上执行不需要的操作。

此外，当操作系统打包人员想要获取其正在重新打包的发行版的元数据时，他可能会遇到一些问题来理解他正在使用的 setup.py 文件。

因此，此 PEP 的基本原理是提供一种方法，可以在 setup.py 旁边的一个静态配置文件中声明元数据，该配置文件不需要任何第三方代码来运行。

在 setup.cfg 中添加 metadata 部分

我们首先要引入一个 [metadata] 部分，在 setup.cfg 文件中，它可能包含元数据中的任何字段。

[metadata]
name = Distribute
version = 0.6.4

setup.cfg 文件用于避免在 Distutils 中添加另一个需要处理的配置文件。

执行命令时，Distutils 已经读取了此文件，如果找到 metadata 部分，它将用于填充元数据字段。如果将对应于元数据字段的选项提供给 setup()，它将覆盖可能存在于 setup.cfg 中的值。

请注意，仍然使用 setup.py，并且可能需要它来定义一些不是元数据字段一部分的选项。例如，sdist 命令可以使用 packages 或 scripts 等选项。

多行值

某些元数据字段可以有多个值。为了保持 setup.cfg 与 ConfigParser 和 RFC 822 LONG HEADER FIELDS（参见第 3.1.1 节）的兼容性，这些值以逗号分隔表示。

requires = pywin32, bar > 1.0, foo

读取此变量时，值将被解析并转换为列表：['pywin32', 'bar > 1.0', 'foo']。

上下文相关部分

metadata 部分还将能够使用上下文相关部分。

上下文相关部分是一个关于执行环境的条件部分。以下是一些示例

[metadata]
name = Distribute
version = 0.6.4

[metadata:sys_platform == 'win32']
requires = pywin32, bar > 1.0
obsoletes = pywin31

[metadata:os_machine == 'i386']
requires = foo

[metadata:python_version == '2.4' or python_version == '2.5']
requires = bar

[metadata:'linux' in sys_platform]
requires = baz

仅当读取文件时满足条件时，才会使用每个 [metadata:condition] 部分。这些上下文相关部分的背景动机是能够定义根据可能安装发行版的平台而变化的需求。（参见 PEP 314）。

其背后的微型语言尽可能简单：它仅使用 == 和 in 运算符（及其反义词）比较字符串，并能够组合表达式。这也使得非 Python 程序员易于理解。

伪语法为

EXPR [in|==|!=|not in] EXPR [or|and] ...

其中 EXPR 属于以下任何一种

• python_version = ‘%s.%s’ % (sys.version_info[0], sys.version_info[1])
• os_name = os.name
• sys_platform = sys.platform
• platform_version = platform.version()
• platform_machine = platform.machine()
• 一个自由字符串，例如 2.4 或 win32

请注意，in 仅限于字符串，这意味着无法在右侧使用其他序列（如元组或列表）。

Distutils 将提供一个函数，该函数能够根据执行环境生成发行版的元数据，给定一个 setup.cfg 文件。

>>> from distutils.util import local_metadata
>>> local_metadata('setup.cfg')
<DistributionMetadata instance>

这意味着普通的 Python 将能够读取包的元数据，而无需运行任何第三方代码。

请注意，此功能不限于 metadata 命名空间。因此，任何其他部分都可以使用此类上下文相关部分进行扩展。

对 PKG-INFO 生成和 PEP 314 的影响

当 Distutils 生成 PKG-INFO 时，每个依赖于条件的字段都将在行尾添加一个条件，在分号分隔符之后。

Metadata-Version: 1.2
Name: distribute
Version: 0.6.4
...
Requires: pywin32, bar > 1.0; sys_platform == 'win32'
Requires: foo; os_machine == 'i386'
Requires: bar; python_version == '2.4' or python_version == '2.5'
Requires: baz; 'linux' in sys_platform
Obsoletes = pywin31; sys_platform == 'win32'
...
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Python Software Foundation License

请注意，可以使用 DistributionMetadata 类打开此文件。此类将能够使用执行环境中的微型语言。

让我们在 Python 2.5 i386 Linux 上运行它。

>>> from distutils.dist import DistributionMetadata
>>> metadata = DistributionMetadata('PKG_INFO')
>>> metadata.get_requires()
['foo', 'bar', 'baz']

如果我们想获取另一个环境的元数据，可以覆盖执行环境。

>>> env = {'python_version': '2.4',
...        'os_name': 'nt',
...        'sys_platform': 'win32',
...        'platform_version': 'MVCC++ 6.0'
...        'platform_machine': 'i386'}
...
>>> metadata = DistributionMetadata('PKG_INFO', environment=env)
>>> metadata.get_requires()
['bar > 1.0', 'foo', 'bar']

PEP 314 已相应更改，这意味着每个字段都将能够拥有该额外的条件标记。

兼容性

此更改基于新的元数据 1.2 格式，这意味着 Distutils 将能够区分旧的 PKG-INFO 文件和新的 PKG-INFO 文件。

setup.cfg 文件更改将保持与 ConfigParser 兼容，并且不会破坏现有的 setup.cfg 文件。

限制

我们目前没有提供 < 和 > 运算符，并且 python_version 是一个常规字符串。这意味着当某个部分需要限制在几个 Python 版本时，需要使用 or 运算符。但是，如果 PEP 386 被接受，python_version 可以内部更改为可与字符串比较的内容，并且可以引入 < 和 > 运算符。

最后，如果某个发行版无法在 setup.cfg 中设置所有元数据字段，也没关系，当调用 local_metadata 时，这些字段将设置为 UNKNOWN。获取 UNKNOWN 值意味着可能需要运行 setup.py 命令行界面以获取完整的元数据集。

致谢

Distutils-SIG。

版权

本文档已进入公有领域。