Openstack keystone setup.py和setup.cfg的解析

在每个openstack项目中，都有setup.py和setup.cfg这两个文件。那setup.py和setup.cfg是什么？如何使用？以keystone项目为例，进行实践和解析。
简单的说，setup.py和setup.cfg是控制python项目打包、安装的工具类。
Setup.py
我们从一个简单的例子开始。假设要分发一个叫foo的模块，文件名foo.py，那么setup.py的内容如下：

fromdistutils.core import setup setup(name='foo',version='1.0',py_modules=['foo'],)

然后，运行pythonsetup.py sdist为模块创建一个源码包。

stack@liujunpeng-Inspur-Computer:~/python_setup$python setup.py sdist runningsdist runningcheck warning:check: missing required meta-data: url warning:check: missing meta-data: either (author and author_email) or(maintainer and maintainer_email) must be supplied warning:sdist: manifest template 'MANIFEST.in' does not exist (usingdefault file list) warning:sdist: standard file not found: should have one of README,README.txt writingmanifest file 'MANIFEST' creatingfoo-1.0 makinghard links in foo-1.0... hardlinking foo.py -> foo-1.0 hardlinking setup.py -> foo-1.0 Creatingtar archive removing'foo-1.0' (and everything under it)

在当前目录下，会创建dist目录，里面有个文件名为foo-1.0.tar.gz，这个就是可以分发的包。使用者，把该包解压，然后执行pythonsetup.pyinstall命令，就把该包安装到了pyhon的类库下面，一把会安装在/usr/local/lib/python2.7/dist-packages/目录下面。

Setup.py还支持将项目打包成可执行文件。如windows下的exe，执行pythonsetup.py
bdist_wininst；Rehdat系列操作系统下面，打包成rpm包，执行命令pythonsetup.py
bdist_rpm。使用pythonsetup.py bdist –help-fromats命令可以查看支持的打包格式。

执行sdist命令时，默认会打包那些东西呢？
1、所有由py_modules或packages指定的源码文件
2、所有ext_modules或libraries指定的C源码文件
3、由script指定的脚本文件
4、类似于test/test*.py的文件
5、README.txt或者README,setup.py,setup.cfg
6、所有package_data
以上参数都是setup函数支持的参数。

通过MANIFEST模版MANIFEST.in文件也可以定义分发包中需要包含的文件。Keystone项目中MANIFEST.in文件内容如下：

includeAUTHORS includebabel.cfg includeChangeLog includeCONTRIBUTING.txt includeLICENSE includeHACKING.rst includeREADME.rst includeopenstack-common.conf includerun_tests.py includerun_tests.sh includesetup.cfg includesetup.py includeTODO includetox.ini includeetc/* includehttpd/* graftbin graftdoc graftkeystone/tests grafttools graftexamples recursive-includekeystone *.json *.xml *.cfg *.pem README *.po *.pot *.sql global-exclude*.pyc *.sdx *.log *.db *.swp keystone/tests/tmp/*

Setup.cfg
setup.cfg提供setup.py的默认参数，同时易于修改。Setup.py先解析setup.cfg文件，然后执行相关命令。在setup.cfg支持setctions：
1、global定义Distutils2的全局选项，可能包含commands、compilers，setup_hook（定义脚本，在setup.cfg被读取后执行，可以修改setup.cfg的配置）
2、metadata
3、files。Package_root、packages、modules、scripts、extra_files
4、commandsections
keystone项目中的setup.cfg文件部分内容如下：

[metadata] name= keystone version= 2015.2 summary= OpenStack Identity description-file= README.rst author= OpenStack author-email= openstack-dev@lists.openstack.org home-page= http://www.openstack.org/ classifier= Environment:: OpenStack IntendedAudience :: Information Technology IntendedAudience :: System Administrators License:: OSI Approved :: Apache Software License OperatingSystem :: POSIX :: Linux ProgrammingLanguage :: Python ProgrammingLanguage :: Python :: 2 ProgrammingLanguage :: Python :: 2.7 [files] packages= keystone [global] setup-hooks= pbr.hooks.setup_hook [egg_info] tag_build= tag_date= 0 tag_svn_revision= 0 [build_sphinx] all_files= 1 build-dir= doc/build source-dir= doc/source [compile_catalog] directory= keystone/locale domain= keystone

PBR
pbr是setuptools的辅助工具，最初为openstack开发，基于d2to1。Pbr会读取和过滤setup.cfg中的内容，然后将解析后的数据提供给setup.py作为参数，包括以下功能：
1、从gti中获取Version，AUTHORS和ChangeLog信息
2、SphinxAutodoc。pbr会扫描project，找到所有模块，生成stubfiles
3、Requirements。读取requirements.txt文件，生成setup函数需要依赖包
4、long_description。从README.rst、README.txt或者READMEfile中生成long_description参数
那如何是使用pbr呢，其实很简单，keystone中是这样使用的。

setuptools.setup( setup_requires=['pbr'], pbr=True)

Babel
openstack项目中是通过Babel库实现国际化的。Babel提供了对distutils或setuptools的支持，包括一些命令。
1、compile_catalog。编译目录，从PO文件中提取message，并编译进二进制的MO文件。

$./setup.py
compile_catalog --directory foobar/locale --locale pt_BR

2、extract_messages，从源码文件中提取本地化字符串，生成PO模板

$./setup.py
extract_messages --output-file foobar/locale/messages.pot

3、update_catalog
基于PO模板文件更新已存在的翻译目录

总结
主要介绍了setup.py、setup.cfg、顺带说明了PBR和Babel对setup.py的支持和如何使用。

致谢
整理这个知识时，参加了网络上不少博客文章，比如chris的博客http://blog.sina.com.cn/s/blog_4951301d0101etvj.html。感谢无私贡献的博主。