目录

摘要[返回到目录]

项目管理的主要工作是：

下面的介绍将按照以上方面展开。

Setuptools 简介[返回到目录]

Setuptools 是 disutils（Python 2.6+）的增强版，它使开发者可以更容易地构建和分发 Python 包，尤其是依赖其它包的包。

对用户来说，使用 Setuptools 构建和分发的包看起来与基于 distuils 的 Python 包一样。为了使用 Setuptools，用户不必安装或了解它们，开发者也不必在发行版中包含全部 Setuptools 工具。在用户没有安装 Setuptools 的情况下，只要源码包中包含 bootstrap 模块（一个 12K 的 .py 文件），那么在构建源码包时，就会自动地下载和安装 Setuptools。

功能亮点

安装 Setuptools[TOC]

请按照 EasyInstall 安装说明来安装 Setuptools。需要特别强调的是：使用 easy_install 时，如果想要把包安装到 Python 的 site-packages 目录之外的地方，那么可以参考下面的自定义安装位置区域。

自定义安装位置：

默认情况下，EasyInstall 会把包安装到 Python 的主 site-packages 目录，然后通过在该目录下自定义一个 .pth 文件的方式，来管理包。

但是经常有这样的需求：用户或开发者想使用 easy_install 将包安装到 site-packages 之外的地方。有许多方式来实现自定义安装，下面列出了最简单和最有意义的几种方式：

补充说明：

1， 可以通过执行如下命令：

来获取 site-packages 的路径。

2，在计算 site-packages 路径时，Python 可执行程序会根据自身计算出 sys.prefix(也可以通过 PYTHONHOME 环境变量为 sys.prefix 设置值)，然后根据 sys.prefix、操作系统、Python 版本计算出 site-packages 的位置

基本使用[TOC]

下面是一个最小化的 setup 脚本：

可以看到，通过使用 Setuptools，不需要做太多事情，就能够为项目生成 egg，将项目上传到 PYPI，自动地包含 setup.py 所在的目录中的所有包。

在把项目发布到 PYPI 之前，可以给 setup 脚本添加一些 metadata，来帮助使用者发现和了解项目。并且项目可能包含依赖、数据文件和脚本：

常用命令[TOC]

1，常规命令：

2，上传到 PyPI：

Setuptools 和 distutils 提供 register 和 upload 命令，用于向 PyPI 推送元数据（<project_name>.egg-info/ 目录下的文件）和发行版文件(dist/ 目录下的文件)。为了将包发布到 PyPI，需要执行下列操作：

列出全部包[返回到目录]

packages 参数用于指定包名列表，Setuptools 会处理（构建、发布、安装等）该列表中列出的每个包中的所有纯 Python 模块（如果想要处理某个包的子包，那么应该在 packages 中列出该子包，比如 packages=["foo", "foo.bar"]）。

package_dir 参数用于将包名映射到文件系统的目录上。其值是一个字典，其中 key 是包名（Setuptools 会自动地将父包的映射应用到子包上，因此无需在 package_dir 参数中指定子包的映射关系），value 是相对于项目根目录（即 setup.py 所在的目录）的目录。当包名为空时，value 所指定的目录代表“包的根目录”，Setuptools 会去“包的根目录”下寻找所有未指定映射关系的包。比如：

在上面的例子中，Setuptools 会将 lib/ 目录当作包 foo，将 lib/bar/ 目录当作包 foo.bar，因此会寻找 lib/__init__.py 和 lib/bar/__init__.py。

包的根目录是 src/，Setuptools 会将 src/baz/ 目录当作包 baz，因此会寻找 src/baz/__init__.py。 （之所以寻找 __init__.py 文件，是因为只有包含 __init__.py 文件的目录才是合法的 Python 包）

对于简单的项目，人工地向 setup() 的 packages 参数添加包名就足够了。然而对于大型项目，保持包名列表的更新是非常大的负担。为了解决这个麻烦，可以通过 setuptools.find_packages() 函数来生成包名列表。

find_packages() 的第一个参数是源代码目录。如果省略该参数，那么它的缺省值是 setup.py 所在的目录。对于使用 src/ 或 lib/ 目录作为源代码树的根目录的项目，应该使用 "src" 或 "lib" 作为 find_packages() 的第一个参数（这类项目仍然需要指定 setup() 的 package_dir 参数，比如 package_dir={"": "src"}）。

find_packages() 的另外两个参数是两个包名模式的列表：

find_packages() 会递归地遍历源代码目录，寻找 Python 包，并使用包含模式列表过滤，最终再移除掉被排除模式列表匹配的包。

在包含模式和排除模式中，可以包含通配符。比如 find_packages(exclude=["*.tests"]) 会排除所有名称的最后一部分是 tests 的包；find_packages(exclude=["*.tests", "*.tests.*"]) 会排除掉任何名称包含 tests 的子包。

之所以使用 find_packages() 来设置 setup() 的 package 参数，是因为即使项目增加顶级包或子包，也不必修改 setup 脚本。

列出单独的模块[返回到目录]

可以通过 py_modules 参数列出要处理的所有纯 Python 模块。这些模块既可以在“包的根目录”下，也可以在某个包中。比如：

在上面的例子中，Setuptools 会去 src/ 目录下寻找 mod1.py，src/pkg/subpkg/ 目录下寻找 mod2.py。

描述扩展模块[返回到目录]

TODO

安装“包数据”[返回到目录]

通常情况下，需要将一些文件安装到包中，这些文件通常是跟包的实现紧密相关的数据或者是包含说明文档的文本文件。这些文件被称为“包数据”。

在 setup() 中，跟“包数据”相关的参数有：

include_package_data：

如果将 include_package_data 设置为 True，那么 Setuptools 会自动地安装包目录下的所有数据文件，这些数据文件必须在 CVS 或 Subversion 的控制之下，或者必须通过 distutils 的 MANIFEST.in 文件指定它们。

关于 MANIFEST.in 文件的详细介绍，可以参考官网。下面仅做简要的说明。

项目中的 MANIFEST.in 文件主要用来定义在发行版中包含哪些文件，MANIFEST.in 中的每行是一个命令，这个命令用来指定包含或排除哪些文件。比如：

能够出现在清单文件 MANIFEST.in 中的命令包括：

命令描述
include pat1 pat2 ...包含名称匹配列表中任意模式的所有文件
exlude pat1 pat2 ...排除名称匹配列表中任意模式的所有文件
recursive-include dir pat1 pat2 ...递归地包含 dir 目录下，名称匹配列表中的任意模式的所有文件
recursive-exclude dir pat1 pat2 ...递归地排除 dir 目录下，名称匹配列表中的任意模式的所有文件
prune dir排除 dir 下的所有文件
graft dir包含 dir 下的所有文件

package_data：

如果数据文件不在 VCS 的控制之下，或者在一个不被支持的 VCS 的控制之下，或者想要细粒度地控制包含哪些文件，那么需要使用 package_data 关键字参数，比如：

package_data 参数是映射包名称到 glob 模式列表的字典。如果数据文件在包的子目录中，glob 模式可以包含子目录名称。比如包目录树如下：

那么可以这样编写 setup 文件：

在 package_data 参数中，当包名为空时，那么对应的模式列表会被应用到所有包（即使这些包已经列出自己的模式），因此在上面的例子中，虽然没在 mypkg 的模式中列出 mypkg.txt，但仍然会包含它。

如果使用路径，那么必须使用 \/ 作为路径分隔符（即使是在 Windows 系统上），Setuptools 在 build 期间会自动地把 \/ 转换成平台相关的分隔符。

有时单独使用 include_package_data 或 package_data 参数，不能精确地定义包含哪些文件。比如想要在版本控制系统和源代码中包含 README.txt 文件，但是在安装时不包含它。对此 Setuptools 提供了 exclude_package_data 参数，其用法如下：

与 package_data 参数一样，exclude_package_data 也是映射包名到 glob 模式列表的字典，在使用这个选项时，空的键会把给定的模式列表应用到所有包，匹配这些模式的任何文件在安装时都会被排除，即使这些文件在 package_data 中被列出来或者被 include_package_data 包含进来。

综上所述，可以通过下面三个选项来包含“包数据”：

注意：

zip_safe 标记以及 pkg_resources 的资源访问 API[返回到目录]

Setuptools 既支持将 Python 项目安装为 zip 文件，也支持将其安装为目录。如果有访问包中的数据文件或源代码的需求，那么可以将 Python 项目安装为目录。比如：

在这种情形下，可以通过包或模块的 __file__ 属性来寻找数据文件。比如某个模块需要访问它所在目录下的 foo.config 文件：

在基于 PEP 302 的导入钩子中，支持从 zip 文件和 egg 文件导入包或模块。在这种情况下，无法使用 __file__ 属性来定位数据文件。此时应该使用 PEP 302 的 get_data() 扩展。但是使用导入协议非常复杂，因此 egg 运行时系统提供了 pkg_resources 资源管理 API，用于访问数据文件。pkg_resources 模块也是 Setuptools 的一部分。

使用 pkg_resources 时，只需要把包名或模块名和资源文件名一起传递给 resource_string、resource_stream、resource_filename 函数。并且应该尽量使用 resource_string 和 resource_stream，而不是 resource_filename，因为它需要将资源文件抽取到临时目录中，这比返回文件内容或文件句柄代价大。

当资源文件被包含在包的子目录中时，无论在哪个操作系统平台，在资源名称中都必须使用 "/" 作为分隔符。

安装非包数据文件[返回到目录]

我们把不在包中的数据文件称为非包数据文件。在 distutils 中，可以通过 data_files 参数，将不在包中的普通数据文件安装到特定平台的某个位置（比如 /usr/share）。这些数据文件通常是配置文件模版、文档等。比如：

data_files 的值是列表，列表中的每个元素都是二元组，二元组的第一元是将要安装到的位置，第二元是数据文件列表。

Setuptools 把数据文件绑定到 egg 文件或目录中（这是一个特性，而不是 bug）。当 data_files 的某个元素的第一元是相对路径时，那么它是相对发行版的根目录的。pkg_resources 模块的资源管理 API 也支持在某个包中访问其它包中的数据文件，只需要使用 Requirement 代替包名，比如：

上面的例子会返回 “MyProject” 的发行版的根目录下的 “sample.conf” 的文件名。

定义依赖[返回到目录]

在安装包时，Setuptools 会自动地安装依赖。跟依赖有关的信息会被包含在 PythonEgg 的元数据中。

对其它模块或包的依赖可以通过 setup() 函数的 install_requires 关键字参数来指定。其值必须是字符串列表，每个字符用于指定一个依赖包，同时也可以指定版本。

当只使用名称而不指定版本时，表示发行版可以依赖任意版本的模块或包。当依赖特定版本的包或模块时，可以在包名后面指定若干个修饰符，每个修饰符中包含比较操作符和版本号，可用的修饰符包括：

多个修饰符之间使用逗号进行分隔。这些修饰符之间是 “AND” 的关系，即所有修饰符都应该被满足。比如：

修饰符含义
==1.0只兼容 1.0 版本
>1.0, !=1.5.1, <2.0兼容 1.0 到 2.0 之间，除去 1.5.1 的任意版本

项目也可以依赖不在 PyPI 上的包和模块，此时可以通过 dependency_links 参数指定一个 URL 列表，Setuptools 会搜索这些页面，来下载 egg 包或源发行版。比如：

创建脚本[返回到目录]

在 distutils 中，可以通过 setup() 函数的 scripts 关键字参数来指定要安装的脚本。比如：

这样做有点“笨拙”，比如当真正运行的“主函数”是某个模块中的某个函数时，必须为它创建单独的脚本文件。

使用 Setuptools 可以自动地生成脚本。在 Windows 上，还会创建 .exe 文件，因此用户不必改变 PATHEXT 设置。为了使用 Setuptools 的这个特性，需要在 setup 脚本中定义入口点（entry points），比如下面的例子会创建两个控制台脚本 foo、bar，以及一个 GUI 脚本 baz：

当项目被安装到非 Windows 平台上时，Setuptools 会创建 foo、bar、baz 脚本。执行 foo 脚本时，会调用 my_package.some_module 的 main_func；执行 bar 脚本时，会调用 other_module 的 some_func；执行 baz 脚本时，会调用 my_package_gui 的 start_func。这些函数都以无参的形式被调用（在函数中可以通过命令选项或环境变量接受参数），它们的返回值会被传递给 sys.exit()。

在 Windows 平台上，会创建 foo.exe、bar.exe、baz.exe 启动器。.exe 包装会找到合适的 Python 解释器，并使用它执行 .py 或 .pyw 文件。

有时某些项目有一些非必须的依赖，比如在 ReportLab 库被安装时，才提供 PDF 输出，或者在 docutils 库被安装时，才支持 reStructuredText，这种特性被称为 “extra”。在 Setuptools 中，可以通过 setup() 函数的 extras_require 关键字参数来指定可选的依赖。同时也可以通过 install_requires 关键字参数，强制被依赖的项目安装它的某些 extra。比如：

extras_require 关键字参数的值是映射 extra 特性名称到字符串列表的字典。列表中的每个字符串描述了一个可选的依赖。这些可选依赖不会被自动安装，除非直接或间接依赖该项目的其它项目强制要求安装（指定依赖时，在项目名后面的方括号中列出要强制安装的 extra）；使用 EasyInstall 安装包时，也可以用这种方式指定要强制安装的 extra。比如：

假设有朝一日 Project-A 对 PDF 的支持不再需要 ReportLab，那么可以将 PDF 的值设置为空列表，这样就无需更改 Project-B 的 setup 信息：

在 entry points 中，也可以使用 extra 特性。比如：

在上面的例子中，Project-A 包含 “rst2pdf” 脚本，PDF 依赖只有在 “rst2pdf” 脚本运行时，才会被解析。

动态发现服务和插件[返回到目录]

Setuptools 支持通过注册入口点（entry point）的方式，动态地发现服务和插件。比如一个博客工具支持多种输出插件，每种输出插件可以将博客内容输出成一种格式。此时可以定义一个叫 blogtool.parsers 的入口点组，然后把插件注册为一个入口点。在运行时，博客工具可以通过查找入口点，找到对应的输出插件。比如下面的例子是将 .rst 输出插件注册到 blogtool.parsers 组：

setup() 函数的 entry_points 参数的值要么是 .ini 风格的字符串，要么是映射入口点组名称到字符串或字符串列表的字典，其中每个字符串是一个入口点说明符，入口点说明符包含名称和值，名称和值之间用等号分隔。值包含用点分隔的模块名，模块名后面是冒号，冒号后面是点分隔的、出现在模块中的对象名；接下来是放在方括号中的 extra 列表（可选）。在加载入口点时，任何通过 extra 指定的依赖，都会被传递给 pkg_resources.require() 函数，因此当被依赖的包缺失时，会打印相应的错误信息。下面看一个简单的例子：

项目结构如下所示：

dynamic_discovery_plugins/__init__.py 的内容如下：

setup.py 的内容如下：

假设 test_plugins.py 已经在 sys.path 下：

在导入 dynamic_discovery_plugins 包时，将打印如下信息：

可执行的egg文件[返回到目录]

偶尔有想使 egg 文件可以直接执行的情况。可以通过包含如下所示的入口点（entry point）的方式，来完成这件事：

任何通过上面的 setup 脚本构建而来的 egg 文件，都会包含一个简短的头：从 my_package.some_module 导入并调用 main_func，在 unix-like 平台上可以通过 /bin/sh 或赋予这个 egg 文件可执行权限的方式，来执行这个 egg 文件。

这个特性的主要意图是支持在非 Windows 平台上安装 Setuptools 自己。值得注意的是带有 eggsecutable 头的 egg 文件不能被重命名，也不能通过符号链接来执行，否则会以错误退出。

集成单元测试[返回到目录]

在进行测试驱动开发时或运行自动化构建之前都需要执行单元测试。可以使用 test 命令在部署之前，运行项目的单元测试。为了使用这个命令，项目的单元测试必须被封装进 unittest 的 TestSuite 中。比如：

当 test_suite 参数的值是包时，Setuptools 会递归地把该包下所有的模块和子包中的测试用例加载到整个 TestSuite 中（如果通过 test_loader 关键字指定了 TestLoader，那么这个处理规则可能会发生改变）。

参考资料[返回到目录]