Python 高手编程系列二百四十三：setup.cfg

setup.cfg 文件包含 setup.py 脚本命令的默认选项。如果构建和分发包的过程更
加复杂，并且需要向 setup.py 命令中传入许多可选参数，那么这个文件非常有用。你可
以按项目将这些默认参数保存在代码中。这将使你的分发流程独立于项目之外，也能够让
包的构建方式与向用户和其他团队成员的分发方式变得透明。
setup.cfg 文件的语法与内置 configparser 模块提供的语法相同，因此它类似于
常见的 Microsoft Windows INI 文件。下面是安装配置文件的示例，提供了 global、sdist
和 bdist_wheel 命令的默认值，代码如下：
[global]
quiet=1
[sdist]
formats=zip,tar
[bdist_wheel]
universal=1
这个配置示例可以确保源代码发行版总是以两种格式创建（ZIP 和 TAR），并且构建
wheel 发行版将被创建为通用 wheel（与 Python 版本无关）。此外，由于全局 quiet 开关，
每个命令的大部分输出都将被阻止。注意，这只是为了便于说明，默认阻止每个命令的输
出可能并不是一个合理的选择。
MANIFEST.in
使用 sdist 命令构建发行版时，distutils 将浏览包的目录，查找需要包含在存档
中的文件。distutils 将包含：
• py_modules、packages 和 scripts 选项隐含的所有 Python 源文件。
• ext_modules 选项列出的所有 C 源文件。
匹配 glob 模式 test/test*.py 的文件包括：README、README.txt、setup.py
和 setup.cfg。
此外，如果你的包是由 subversion 或 CVS 管理，那么 sdist 将浏览诸如.svn 之类的
文件夹，查找需要包含的文件。利用扩展也可以与其他版本控制系统集成。sdist 将构建
一个 MANIFEST 文件，列出所有文件并将它们包含在存档中。
假设你不使用这些版本控制系统，并且需要包含更多的文件。现在，在与 setup.py
相同的目录中，你可以为 MANIFEST 文件定义一个名为 MANIFEST.in 的模板，在其中你
可以指定 sdist 要包含哪些文件。
这个模板的每一行都定义一条包含或排除规则，例如：
include HISTORY.txt
include README.txt
include CHANGES.txt
include CONTRIBUTORS.txt
include LICENSE
recursive-include *.txt *.py
MANIFEST.in 命令的完整列表可以在 distutils 官方文档中找到。
最重要的元数据
除了被分发包的名称和版本之外，setup 可以接受的最重要的参数包括。
• description：包含描述包的几句话。
• long_description：包含完整说明，可以使用 reStructuredText 格式。
• keywords：定义包的关键字列表。
• author：作者的姓名或组织。
• author_email：联系人电子邮件地址。
• url：项目的 URL。
• license：许可证（GPL、LGPL 等）。
• packages：包中所有名称的列表；setuptools 提供了一个名为 find_packages
的小函数来计算它。
• namespace_packages：命令空间包的列表。
trove 分类器
PyPI 和 distutils 为应用程序分类提供了一种解决方案，就是使用一套被称为 trove
分类器（trove classifiers）的分类器。所有分类器都形成一个树状结构。每个分类器都是字符
串形式，其中用::字符串分隔每个命名空间。分类器列表在包定义中是作为 setup()函数
的 classifiers 参数。下面是 PyPI 上某个项目的分类器列表示例（这里是 solrq 项目）：
from setuptools import setup
setup(
name=“solrq”,

(…)

classifiers=[
‘Development Status :: 4 - Beta’,
‘Intended Audience :: Developers’,
‘License :: OSI Approved :: BSD License’,
‘Operating System :: OS Independent’,
‘Programming Language :: Python’,
‘Programming Language :: Python :: 2’,
‘Programming Language :: Python :: 2.6’,
‘Programming Language :: Python :: 2.7’,
‘Programming Language :: Python :: 3’,
‘Programming Language :: Python :: 3.2’,
‘Programming Language :: Python :: 3.3’,
‘Programming Language :: Python :: 3.4’,
‘Programming Language :: Python :: Implementation :: PyPy’,
‘Topic :: Internet :: WWW/HTTP :: Indexing/Search’,
],
)
它们在包定义中是完全可选的，但可以对 setup()接口中可用的基本元数据提供有用
的扩展。此外，trove 分类器还可以提供以下信息：支持的 Python 版本或系统、项目的开发
阶段或发布代码所使用的许可证。许多 PyPI 用户按类别对可用的包进行搜索和浏览，因此
正确的分类可以让 Python 包找到目标客户。
trove 分类器在整个打包生态系统中发挥重要作用，不应该被忽略。没有一个组织来验
证包的分类，所以你有责任为你的包提供正确的分类器，并且不要为整个包索引带来混乱。
在编写本书时，PyPI 上共有 608 个可用的分类器，分为以下 9 类。
• 开发状态（Development Status）。
• 环境（Environment）。
• 框架（Framework）。
• 目标受众（Intended Audience）。
• 许可证（License）。
• 自然语言（Natural Language）。
• 操作系统（Operating System）。
• 编程语言（Programming Language）。
• 话题（Topic）。
由于不时会添加新的分类器，所以在你阅读本书时这些数字可能会有所不同。当前可
用的 trove 分类器的完整列表可以用 setup.py register --list-classifiers 命
令来查看。