通过demo学习OpenStack开发——软件包管理

jopen 8年前

通过demo学习OpenStack开发–软件包管理

编者按:《通过demo学习OpenStack开发》专栏是刘陈泓的系列文章,专栏通过开发一个demo的形式来介绍一些参与OpenStack项目开发的必要的基础知识,希望帮助大家入门企业级Python项目的开发和OpenStack项目的开发。刘陈泓主要关注OpenStack的身份认证和计费领域。另外,还对云计算、分布式系统应用和开发感兴趣。

为什么写这个系列

OpenStack 是目前我所知的最大最复杂的基于Python项目。整个OpenStack项目包含了数十个主要的子项目,每个子项目所用到的库也不尽相同。因此,对于Python初学者和未接触过OpenStack项目的人Python来说,入门的难度相当大。

幸运的是,OpenStack中的项目有很多共同点。比如,它们有相同的代码库结构,都尽可能是用同样的库,配置文件和单元测试的规范也都几乎一样。因此,通过学习这些共通的部分,我们就可以快速掌握多个OpenStack项目。但是,万事开头难,学习这些基础知识总是痛苦的。不过,学习的难点并不在于这些知识点本身有多难理解,而是这些基础知识的应用场景和应用效果对初学者来说都是模糊的。这个系列文章的目的就是帮助有需要的人了解OpenStack中一些常见的知识点。理解过程就是通过动手做一个Web application demo来实现的。

这个系列文章会涉及到以下的知识点:

  • 包管理和pbr
  • WSGI, RESTful Service和Pecan框架
  • eventlet
  • SQLAlchymy
  • 单元测试

下面的知识点是不会专门讲的,如果有遇到不会的请自学:

  • git

软件包管理

软件包管理是每个OpenStack项目的基础,其目的是用来将项目代码打包成源码包或者二进制包进行分发。一个项目的代码可能会被打包放到PyPI上,这样你可以通过 pip 命令安装这个包;也可能会被打包放到项目的软件仓库里,这样你可以通过 apt-get install 或者 yum install 来安装这个软件包。

不幸的是,Python在软件包管理十分混乱,至少历史上十分混乱。原因有两个:

  • 一是标准库提供的软件包管理功能十分弱,
  • 二是官方没有提供统一的软件包管理标准。

对于这个领域,我曾经也是混乱的,只知道使用easy_install和pip来安装软件包。不过自从看了 The Hacker’s Guide to Python (《Python高手之路》)之后,算是知道点来龙去脉。

软件打包工具的历史

这里我会讲一下我知道的Python的软件打包工具的历史,我们按照历史顺序来叙述。

distutils (before 2000)

disutils自从1998年起就是Python标准库的一部分了,不过它在2000年就停止了开发。disutils是最早的Python打包工具和标准,也奠定了对Python软件进行打包的一个基本工作方式: 使用setup.py文件 。来看一个setup.py文件的例子:

#!/usr/bin/env Python  # -*- coding: utf-8 -*-    from disutils.core import setup    setup(name='webdemo',        description='A simple web demo.',        author='author name',        author_email='author_name@example.com'        url='http://example.com',        packages=['webdemo'])

setup.py文件是放在项目根目录下的:

➜ ~/programming/Python/webdemo git:(master) ✗ $ ls  LICENSE  README.md  setup.py  webdemo

然后你就可以使用命令 Python setup.py build 来编译包,可以使用 Python setup.py install 来安装这个项目。如果需要帮助,可以通过 Python setup.py --help-commands 来查看支持的命令。

setuptools

disutils停止开发后,setuptools成了继任者。setuptools提供了很多高级功能,包括自动依赖处理、Egg分发格式以及 easy_install 命令。setuptools的使用方式和disutils差不多,也是以一个setup函数作为入口,只不过该函数来自于setuptools模块,而且支持更多的参数,比如classifiers, setup_requires等,参数更多意味着功能更多。

后来有一段时间setuptools项目发展开始变得缓慢了,就有人从setuptools项目创建了 distribute 项目。distribute开始支持Python 3等新特性。不过一段时间后,distribute项目又和setuptools项目合并了(2013年3月)。因此,现在已经不存在distribute项目了。

到目前为止,setuptools还是使用最多的打包工具,而且开发很活跃,2015年6月刚刚发布了18.0版本。 setuptools项目的文档 。OpenStack目前也是使用setuptools库来执行打包操作,我们下面会详细点介绍setuptools工具。

disutils2

在setuptools项目发展的过程中,有一个叫disutils2的项目也在并行开发中,其目的是全面取代Python标准库中的distutils。disutils2的最大改进是将setup函数的参数单独放到一个setup.cfg的文件中(这些成为包的元数据)。不够disutils2这个项目缺点很多,而且没有功能上还不如setuptools项目,所以在2012年的时候,这个项目被废弃了。

distlib

这个是一个新的打包工具,目标也是取代disutils。不过这个项目的开发进展也不快,到2015年才发布了0.2.0版本。目前还未能并入到Python的标准库中。不过可以保持关注。 项目文档地址

在OpenStack中使用打包工具

前面已经提到了,OpenStack也是使用setuptools工具来进行打包,不过为了满足OpenStack项目的需求,引入了一个辅助工具 pbr 来配合setuptools完成打包工作。

pbr (Python Build Reasonableness)

pbr是一个setuptools的扩展工具,被开发出来的主要目的是为了方便使用setuptools,其项目文档地址也 在OpenStack官网内

先说一下pbr如何使用:

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

按照上面的方式就可以配置setuptools工具使用pbr来协助完成打包工作。这里的 setup_requires 参数意思是setup函数在执行之前需要依赖的包的列表。这里的依赖的包的功能可以理解为生成setup的实际参数。你可以看到,当使用pbr的时候,setup函数只有两个参数,然而实际上 setuptools.setup 函数实际上是 disutils.core.setup 函数,会接收任何参数,这些参数可以通过在调用时指定,也可以通过所依赖的扩展来生成(比如pbr)。

那么OpenStack社区为啥要开发pbr呢?因为setuptools库使用起来还是有点麻烦,参数太多,而且直接通过指定setup函数的参数的方法实在太不方便了。pbr就是为了方便而生的,它带了了如下的改进:

  1. 使用setup.cfg文件来提供包的元数据。这个是从disutils2学来的。
  2. 基于requirements.txt文件来实现自动依赖安装。requirements.txt文件中包含了一个项目所要依赖的库,这个文件的格式是和pip兼容的。
  3. 利用Sphinx实现文档自动化。
  4. 基于git history自动生成AUTHORS和ChangeLog文件。
  5. 针对git自动创建文件列表。
  6. 基于git tags的版本号管理。

pbr的版本推导

这里重点说明一下基于git tag的版本号管理这个功能。当使用pbr的时候,版本号有两种方式: postversioningpreversioning ,postversioning是默认方式。要是用preversioning的方式,则需要设置setup.cfg文件中的 [metadata] 段的 version 字段的值。无论采用哪种方式,版本号都是从git的历史推理得到的。pbr使用的版本号标准是 Linux/Python Compatible Semantic Versioning 3.0.0 ,简单的说就是下面这个标准:

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner,
  3. and PATCH version when you make backwards-compatible bug fixes.

pbr的版本推导按照如下的步骤进行(注意,最终版本号才是软件包的版本号):

  1. 如果设置version的值为一个给定的版本号,且这个版本号刚好对应一个tag,则这个值就是最终版本号(注意,这里只有签名的tag才有效)。
  2. 如果不是上面情况,则pbr会找到最近的一个tag,然后为其MINOR值加1得到一个比它大的最小版本号(注意,这个还不是最终版本号)。
  3. 然后pbr会从最近的一个tag开始遍历所有的git commit,并检查每个提交的commit message,在commit message中查找 Sem-Ver: 这样的行:

    • 如果Sem-Ver的值是 bugfix ,则会增加版本号中PATCH部分的值。
    • 如果Sem-Ver的值是 feature 或者 deprecation ,则会增加版本号中MINOR部分的值。
    • 如果Sem-Ver的值是 api-break ,则会增加版本号中MAJOR部分的值。
    • 如果Sem-Ver行不存在,则认为值是 bugfix
    • 如果Sem-Ver的值不在上面列出的范围内,则会给出警告。

      1. 如果使用的是postversioning的方式,也就是setup.cfg中不指定version的值,则pbr会使用规则3推导出来的值作为目标版本号(只是目标版本号,不是最终版本号)。
      2. 如果使用的是preversioning的方式,也就是setup.cfg中指定了version的值(而且不符合规则1),则会检查指定的version是否高于规则3推导出来的版本号,如果没有,则会抛出异常,如果有,则使用指定的版本号作为目标版本号。
      3. 在得到目标版本号之后,开始计算开发版本号。开发版本号的形式如下: MAJOR.MINOR.PATCH.devN 。这里要计算的是 devN 中的 N 。这个值等于从最近的git tag开始的提交数量。计算完开发版本号之后,就得到了最终版本号。
      </li> </ul> </li> </ol>

      总的来说,从上面的规则计算出来的版本号只有两种形式,一种是发布版本号(对应到某个tag),另一种是开发版本号。注意:pbr要求tag都是要签名的,也就是打tag时要使用 git tag -a -s X.Y.Z 的形式。

      setup.cfg和requirements.txt

      setup.cfg

      由于OpenStack项目都使用了setuptools和pbr来执行打包工作,因此项目的元数据都放在setup.cfg文件中。我们以keystone项目的setup.cfg文件为例来说明这个文件里一般会包含什么内容。以下是写这篇文章时最新的keystone项目的setup.cfg文件的内容(以#开头的是我加的注释):

      [metadata]  # 元数据段  name = keystone  # 软件包名称  version = 8.0.0  # 软件包版本号,还可以指定preversoining, postversioning等值,具体的作用看pbr的文档。  summary = OpenStack Identity  # 简介  description-file =  # 指定README文件      README.rst  author = OpenStack  # 作者  author-email = OpenStack-dev@lists.OpenStack.org  # 作者邮件  home-page = http://www.OpenStack.org/  # 主页  classifier =  # 包的分类,下面具体说      Environment :: OpenStack      Intended Audience :: Information Technology      Intended Audience :: System Administrators      License :: OSI Approved :: Apache Software License      Operating System :: POSIX :: Linux      Programming Language :: Python      Programming Language :: Python :: 2      Programming Language :: Python :: 2.7    [files]  # 文件段  packages =  # 包名称      keystone    [global]  # 全局段  setup-hooks =  # 指定安装hook      pbr.hooks.setup_hook      [egg_info]  # 指定egg信息  tag_build =  tag_date = 0  tag_svn_revision = 0    [build_sphinx]  # 文档build相关信息  all_files = 1  build-dir = doc/build  source-dir = doc/source    [compile_catalog]  directory = keystone/locale  domain = keystone    [update_catalog]  domain = keystone  output_dir = keystone/locale  input_file = keystone/locale/keystone.pot    [extract_messages]  keywords = _ gettext ngettext l_ lazy_gettext  mapping_file = babel.cfg  output_file = keystone/locale/keystone.pot  copyright_holder = OpenStack Foundation  msgid_bugs_address = https://bugs.launchpad.net/keystone    # NOTE(dstanek): Uncomment the [pbr] section below and remove the ext.apidoc  # Sphinx extension when https://launchpad.net/bugs/1260495 is fixed.  [pbr]  # pbr本身的配置  warnerrors = True  autodoc_tree_index_modules = True    [entry_points]  # 指定入口点  console_scripts =  # 指定要生成的可执行文件      keystone-all = keystone.cmd.all:main      keystone-manage = keystone.cmd.manage:main    # 下面是其他entry_points内容,主要用于指定不同功能的扩展,和打包无关。  ...

      ( 上面有些未注释的部分我目前还不太清楚,后续补充,可以先参考 PEP301 )

      这里说说一下classifier这个参数。这个参数是用来指定一个软件包的分类、许可证、允许运行的操作系统、允许运行的Python的版本的信息。这些信息是在一个叫trove的项目。关于Python和trove的关系, 请参考

      你可以在PyPI上找到完整的classifier值列表, 地址 。另外,你也可以通过setuptools的命令来获取这个列表,在项目根目录下执行: Python setup.py register --list-classifiers 。

      requirements.txt

      这个文件指定了一个项目依赖的包有哪些,并且支出了依赖的包的版本需求,可以看看keystone项目的requirements.txt:

      # The order of packages is significant, because pip processes them in the order  # of appearance. Changing the order has an impact on the overall integration  # process, which may cause wedges in the gate later.    pbr<2.0,>=0.11  WebOb>=1.2.3  eventlet>=0.17.4  greenlet>=0.3.2  PasteDeploy>=1.5.0  Paste  Routes!=2.0,>=1.12.3  cryptography>=0.8.2 # Apache-2.0  six>=1.9.0  SQLAlchemy<1.1.0,>=0.9.7  sqlalchemy-migrate>=0.9.6  stevedore>=1.5.0 # Apache-2.0  passlib  Python-keystoneclient>=1.6.0  keystonemiddleware>=1.5.0  oslo.concurrency>=2.1.0 # Apache-2.0  oslo.config>=1.11.0 # Apache-2.0  oslo.messaging!=1.12.0,>=1.8.0 # Apache-2.0  oslo.db>=1.10.0 # Apache-2.0  oslo.i18n>=1.5.0 # Apache-2.0  oslo.log>=1.2.0 # Apache-2.0  oslo.middleware!=2.0.0,>=1.2.0 # Apache-2.0  oslo.policy>=0.5.0 # Apache-2.0  oslo.serialization>=1.4.0 # Apache-2.0  oslo.service>=0.1.0 # Apache-2.0  oslo.utils>=1.6.0 # Apache-2.0  oauthlib>=0.6  pysaml2>=2.4.0  dogpile.cache>=0.5.3  jsonschema!=2.5.0,<3.0.0,>=2.0.0  pycadf>=0.8.0  msgpack-Python>=0.4.0

      软件包归档格式

      Python的软件包一开始是没有官方的标准分发格式的。比如Java有jar包或者war包作为分发格式,Python则什么都没有。后来不同的工具都开始引入一些比较通用的归档格式。比如,setuptools引入了Egg格式。但是,这些都不是官方支持的,存在元数据和包结构彼此不兼容的问题。因此,为了解决这个问题,PEP 427定义了新的分发包标准,名为Wheel。目前pip和setuptools工具都支持Wheel格式。这里我们简单总结一下常用的分发格式:

      • tar.gz格式:这个就是标准压缩格式,里面包含了项目元数据和代码,可以使用 Python setup.py sdist 命令生成。
      • .egg格式:这个本质上也是一个压缩文件,只是扩展名换了,里面也包含了项目元数据以及源代码。这个格式由setuptools项目引入。可以通过命令 Python setup.py bdist_egg 命令生成。
      • .whl格式:这个是Wheel包,也是一个压缩文件,只是扩展名换了,里面也包含了项目元数据和代码,还支持免安装直接运行。whl分发包内的元数据和egg包是有些不同的。这个格式是由PEP 427引入的。可以通过命令 Python setup.py bdist_wheel 生成。

      .egg-info和.dist-info目录

      如果你到系统中安装Python库的路径下看看,就能看到很多名称以.egg-info或者以.dist-info结尾的目录。这些目录的内容就是这个库的元数据,是从库的分发包中拷贝出来的。其中.egg-info类型的目录来自于Egg格式的分发包,.dist-info类型的目录来自于Wheel格式的分发包。

      软件包的安装

      安装工具

      上面已经提到了,setuptools项目提供了一个软件包安装工具 esay_install 。easy_install支持从软件归档文件中或者从PyPI上安装软件包,不过这个工具并不好用,比如缺少卸载功能等,因此并不流行,现在更多的都是使用pip工具。

      pip项目提供了很好的软件包安装方式,并且已经被包含到Python 3.4中,可以从PyPI、tarball或者Wheel归档中安装和卸载软件按包。关于pip常见的用法,这里就不赘述了( pip install, pip uninstall, pip search, … )。

      安装路径

      软件包的安装路径依赖于操作系统、Python版本和安装方式。

      • 在Debian系的系统上(比如Ubuntu)

        • 使用 apt-get install 从系统软件源安装

          • Python 2.7: /usr/lib/Python2.7/dist-packages
          • Python 3.4: /usr/lib/Python3.4/dist-packages
          </li>
        • 使用 pip install 命令安装

          • Python 2.7: /usr/local/lib/Python2.7/dist-packages
          • Python 3.4: /usr/local/lib/Python3.4/dist-packages
          • </ul> </li>
          • 在virtualenv中使用 pip install 安装

            • Python 2.7: lib/Python2.7/site-packages
            • Python 3.4: lib/Python3.4/site-packages
            • </ul> </li> </ul> </li>
            • 在CentOS系的系统上

              • 使用 yum install 命令安装

                • Python 2.7: /usr/lib/Python2.7/site-packages
                • </ul> </li> </ul> </li> </ul>

                  以开发模式安装

                  pip的安装命令可以使用-e选项,用来从本地代码目录或者版本库URL来安装一个开发版本的库。采用这种方式的时候,在安装目录下只会创建一个包含软件包信息的文件,真正的代码不会安装到系统目录下。

                  Webdemo的打包管理

                  学习过包管理相关的知识后,我们就要以OpenStack的方法来创建一个我们自己的项目。这个项目的名称是Webdemo,就是一个简单的Web服务器。这个项目会贯穿这个系列文章。在本文中,我们首先要创建Webdemo的项目框架并添加软件包管理相关的内容。

                  项目目录结构

                  ➜ ~/programming/Python/webdemo git:(master) ✗ $ tree .  .  ├── LICENSE  ├── README.md  ├── requirement.txt  ├── setup.cfg  ├── setup.py  └── webdemo      └── __init__.py    1 directory, 6 files

                  这个是一个最简单的Python项目目录:

                  • 源代码放在子目录Webdemo/下
                  • 然后包含了软件包管理的所需的文件:setup.py, setup.cfg, requirements.txt
                  • LICENSE和README

                  软件包管理相关

                  首先是setup.py,就是这么简单:

                  #!/usr/bin/env Python  # -*- coding: utf-8 -*-    import setuptools      # In Python < 2.7.4, a lazy loading of package `pbr` will break  # setuptools if some other modules registered functions in `atexit`.  # solution from: http://bugs.Python.org/issue15881#msg170215  try:          import multiprocessing  # noqa  except ImportError:          pass      setuptools.setup(      setup_requires=['pbr'], pbr=True)

                  然后是setup.cfg:

                  [metadata]  name = webdemo  version = 0.0.1  summary = Web Application Demo  description-file = README.md  author = author  author-email = author@example.com  classifier =      Environment :: Web Environment      Intended Audience :: Developers      Intended Audience :: Education      License :: OSI Approved :: GNU General Public License v2 (GPLv2)      Operating System :: POSIX :: Linux      Programming Language :: Python      Programming Language :: Python :: 2      Programming Language :: Python :: 2.7    [global]  setup-hooks =      pbr.hooks.setup_hook    [files]  packages =      webdemo    [entry_points]  console_scripts =

                  只包含最基本的信息。接下来是requirements.txt文件:

                  # The order of packages is significant, because pip processes them in the order  # of appearance. Changing the order has an impact on the overall integration  # process, which may cause wedges in the gate later.    pbr<2.0,>=0.11

                  目前只依赖于pbr库。源代码目录下现在只有一个空的 init.py 文件。我们已经搭建好了这个最简单的项目框架了。首先,我们要把这些代码提交到git库,然后打上 tag 0.0.1

                  ➜ ~/programming/Python/webdemo git:(master) ✗ $ git log --oneline  697427c Add packaging information  2cbbf4d Initial commit  ➜ ~/programming/Python/webdemo git:(master) ✗ $ git tag -a -s 0.0.1  ➜ ~/programming/Python/webdemo git:(master) ✗ $ git tag  0.0.1

                  然后就可以使用 Python setup.py sdist 命令来生成一个0.0.1版本的源码归档了:

                  ➜ ~/programming/Python/webdemo git:(master) ✗ $ Python setup.py sdist  running sdist  [pbr] Writing ChangeLog  [pbr] Generating ChangeLog  [pbr] Generating AUTHORS  running egg_info  writing pbr to webdemo.egg-info/pbr.json  writing webdemo.egg-info/PKG-INFO  writing top-level names to webdemo.egg-info/top_level.txt  writing dependency_links to webdemo.egg-info/dependency_links.txt  writing entry points to webdemo.egg-info/entry_points.txt  [pbr] Processing SOURCES.txt  [pbr] In git context, generating filelist from git  warning: no previously-included files found matching '.gitreview'  warning: no previously-included files matching '*.pyc' found anywhere in distribution  writing manifest file 'webdemo.egg-info/SOURCES.txt'  warning: sdist: standard file not found: should have one of README, README.rst, README.txt    running check  warning: check: missing required meta-data: url    creating webdemo-0.0.1  creating webdemo-0.0.1/webdemo  creating webdemo-0.0.1/webdemo.egg-info  making hard links in webdemo-0.0.1...  hard linking AUTHORS -> webdemo-0.0.1  hard linking ChangeLog -> webdemo-0.0.1  hard linking LICENSE -> webdemo-0.0.1  hard linking README.md -> webdemo-0.0.1  hard linking requirement.txt -> webdemo-0.0.1  hard linking setup.cfg -> webdemo-0.0.1  hard linking setup.py -> webdemo-0.0.1  hard linking webdemo/__init__.py -> webdemo-0.0.1/webdemo  hard linking webdemo.egg-info/PKG-INFO -> webdemo-0.0.1/webdemo.egg-info  hard linking webdemo.egg-info/SOURCES.txt -> webdemo-0.0.1/webdemo.egg-info  hard linking webdemo.egg-info/dependency_links.txt -> webdemo-0.0.1/webdemo.egg-info  hard linking webdemo.egg-info/entry_points.txt -> webdemo-0.0.1/webdemo.egg-info  hard linking webdemo.egg-info/not-zip-safe -> webdemo-0.0.1/webdemo.egg-info  hard linking webdemo.egg-info/pbr.json -> webdemo-0.0.1/webdemo.egg-info  hard linking webdemo.egg-info/top_level.txt -> webdemo-0.0.1/webdemo.egg-info  copying setup.cfg -> webdemo-0.0.1  Writing webdemo-0.0.1/setup.cfg  Creating tar archive  removing 'webdemo-0.0.1' (and everything under it)  ➜ ~/programming/Python/webdemo git:(master) ✗ $ ls dist  webdemo-0.0.1.tar.gz  ➜ ~/programming/Python/webdemo git:(master) ✗ $ ls  AUTHORS  ChangeLog  dist  LICENSE  README.md  requirement.txt  setup.cfg  setup.py  webdemo  webdemo.egg-info

                  验证成功,在 dist/ 目录下生成了一个0.0.1版本的源码归档,同时生成了如下的文件和目录: AUTHORS, ChangeLog, webdemo.egg-info

                  </div>

                  来自: http://www.infoq.com/cn/articles/OpenStack-demo-packagemanagement