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的内容如下：

from distutils.core import setup

setup(name='foo',version='1.0',py_modules=['foo'],)

 

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

$python setup.py sdist

running sdist

running check

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，这个就是可以分发的包。使用者，把该包解压，然后执行python setup.py install命令，就把该包安装到了pyhon的类库下面，一把会安装在/usr/local/lib/python2.7/dist-packages/目录下面。

Setup.py还支持将项目打包成可执行文件。如windows下的exe，执行python setup.py bdist_wininst；Rehdat系列操作系统下面，打包成rpm包，执行命令python setup.py bdist_rpm。使用python setup.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文件内容如下：

include AUTHORS

include babel.cfg

include ChangeLog

include CONTRIBUTING.txt

include LICENSE

include HACKING.rst

include README.rst

include openstack-common.conf

include run_tests.py

include run_tests.sh

include setup.cfg

include setup.py

include TODO

include tox.ini

include etc/*

include httpd/*

graft bin

graft doc

graft keystone/tests

graft tools

graft examples

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、command sections

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的支持和如何使用。