摘要

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

拒绝通知

由于 distutils2 将不再被合并到标准库中，此 PEP 已于 2013 年 4 月下旬被 Alyssa Coghlan 拒绝。

将创建一个基于 PEP 426（元数据 2.0）的替代 PEP，它将定义在给定源代码 tarball 或 VCS 检出时生成 sdist 归档所需的最低信息量。

基本原理

今天，如果您想列出分发版（请参阅 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 部分

我们要介绍的第一件事是在 setup.cfg 文件中添加一个 [metadata] 部分，该部分可以包含元数据中的任何字段。

[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。

版权

本文档已置于公共领域。