openstack 使用pbr配置,setup.cfg的格式與含義

pbr - Python Build Reasonableness

A library for managing setuptools packaging needs in a consistent manner.

pbr reads and then filters the setup.cfg data through a setup hook to fill in default values and provide more sensible behaviors, and then feeds the results in as the arguments to a call to setup.py - so the heavy lifting of handling python packaging needs is still being done by setuptools.

Note that we don’t support the easy_install aspects of setuptools: while we depend on setup_requires, for any install_requires we recommend that they be installed prior to running setup.py install - either by hand, or by using an install tool such as pip.

翻譯：

pbr -python 合理編譯工具

這是一個一致的管理python setuptools 的工具庫

pbr模塊讀入setup.cfg文件的信息，而且給setuptools 中的setup hook 函數填寫默認參數，提供更加有意義的行爲，而後使用setup.py來條用，所以setuptools工具包依然是必須的。

注意，咱們並不支持setuptools包中的easy_install工具集，當咱們依賴於安裝需求前提軟件，咱們推薦使用setup.py install方式或者pip方式安裝。

What It Does

PBR can and does do a bunch of things for you:

• Version: Manage version number based on git revisions and tags
• AUTHORS: Generate AUTHORS file from git log
• ChangeLog: Generate ChangeLog from git log
• Manifest: Generate a sensible manifest from git files and some standard files
• Sphinx Autodoc: Generate autodoc stub files for your whole module
• Requirements: Store your dependencies in a pip requirements file
• long_description: Use your README file as a long_description
• Smart find_packages: Smartly find packages under your root package

翻譯：

它能幹什麼

PBR包能夠作如下事情

版本：能夠基於git版本和標籤信息管理版本號

做者:從git的日誌信息產生做者信息

更改日誌：從git日誌中產生軟件包日誌

manifest:從git以及其餘標準文檔中產生一個manifest文件

Sphinx Autodoc:自動產生stub files

需求：生成requirements需求文件

詳細描述：使用你的README文件做爲包的描述

聰明找包：從你的包的根目錄下聰明的找到包

Version

Versions can be managed two ways - postversioning and preversioning. Postversioning is the default, and preversioning is enabeld by setting version in the setup.cfg metadata section. In both cases version strings are inferred from git.

If a given revision is tagged, that’s the version.

If it’s not, then we take the last tagged version number and increment it to get a minimum target version.

We then walk git history back to the last release. Within each commit we look for a Sem-Ver: pseudo header, and if found parse it looking for keywords. Unknown symbols are not an error (so that folk can’t wedge pbr or break their tree), but we will emit an info level warning message. Known symbols: feature, api-break, deprecation, bugfix. A missing Sem-Ver line is equivalent to Sem-Ver: bugfix. The bugfix symbol causes a patch level increment to the version. The feature and deprecation symbols cause a minor version increment. The api-break symbol causes a major version increment.

If postversioning is in use, we use the resulting version number as the target version.

If preversioning is in use - that is if there is a version set in setup.cfg metadata - then we check that that version is higher than the target version we inferred above. If it is not, we raise an error, otherwise we use the version from setup.cfg as the target.

We then generate dev version strings based on the commits since the last release and include the current git sha to disambiguate multiple dev versions with the same number of commits since the release.

翻譯：

版本：版本可使用兩種方式管理-postversioning，preversioning管理。postversioning是默認方式，preversioning經過在setup.cfg文件的metadata項目下面設置版本信息控制。兩種狀況下，都從git中獲取版本的字符串信息。

若是指定修改設置了標籤，那麼就是版本。若是沒有，咱們則使用最後一次被標籤記錄的版本號。在其上遞增獲取目標版本。

咱們而後便利git的歷史信息，回到最後的發佈。在每次提交，咱們尋找Sem-Ver:假的header，若是找到解析的關鍵字.不認識的符號非錯誤（所以人們不會破壞pbr和樹形結構），可是咱們會發出一個警告信息。已知的符號：feature,apt-break,deprecation,bugfix.一個缺失的Sem-Ver 行等於Sem-Ver:bugfix.bugfix符號致使該版本上增長一個patch。feature和deprecation符號致使最小的版本遞增。api-break符號致使最大的版本遞增。

若是使用postversioning，咱們使用resulting 版本號做爲目標版本。

若是使用preversioning，那就是說在setup.cfg的metadata欄目中有設置版本信息，那麼咱們將檢查比以上咱們提到的目標版本更加大的版本號。若是沒有，咱們將引起一個錯誤，不然咱們使用setup.cfg中的定義的版本號做爲目標版本號。

基於最後發佈的提交，咱們產生一個dev 版本的字符串。而後使用目前git的sha字符串來區分多個dev 版本中使用相同號碼的提交。

Note

pbr expects git tags to be signed for use in calculating versions

The versions are expected to be compliant with Linux/Python Compatible Semantic Versioning 3.0.0.

The version.SemanticVersion class can be used to query versions of a package and present it in various forms - debian_version(), release_string(), rpm_string(), version_string(), or version_tuple().

注意：

pbr經過git的標籤來計算版本。

版本與inux/Python Compatible Semantic Versioning 3.0.0.兼容。

 version.SemanticVersion類能夠經過查詢包的版本號，而後經過不一樣形式展示：debian_version(), release_string(), rpm_string(), version_string(), or version_tuple().

AUTHORS and ChangeLog

Why keep an AUTHORS or a ChangeLog file when git already has all of the information you need? AUTHORS generation supports filtering/combining based on a standard .mailmap file.

做者以及變動日誌

有什麼必要重做一份，當git已經有了做者與變動日誌的記錄呢？可以依據.mailmap文件自動過濾組合成做者信息。

Manifest

Just like AUTHORS and ChangeLog, why keep a list of files you wish to include when you can find many of these in git. MANIFEST.in generation ensures almost all files stored in git, with the exception of .gitignore, .gitreview and .pyc files, are automatically included in your distribution. In addition, the generated AUTHORS and ChangeLog files are also included. In many cases, this removes the need for an explicit ‘MANIFEST.in’ file

就像做者和變動日誌，有什麼必要維護一份文件列表信息，當git已經在.mainfest 中維護了一份除了.gitignore,gitreview,.pyc等文件的其餘的信息。在多個狀況下，能夠除掉MAINFEST.in文件。

Sphinx Autodoc

Sphinx can produce auto documentation indexes based on signatures and docstrings of your project but you have to give it index files to tell it to autodoc each module: that’s kind of repetitive and boring. PBR will scan your project, find all of your modules, and generate all of the stub files for you.

Sphinx documentation setups are altered to generate man pages by default. They also have several pieces of information that are known to setup.py injected into the sphinx config.

See the pbr section for details on configuring your project for autodoc.

Sphinx 自動文檔

Sphinx 能夠自動產生文檔索引基於你的項目中的標籤與文檔字符串(代碼中""" ..."""部分).可是你得告訴它每一個模塊的索引文件位置：這種 工做重複性且無聊。PBR會自動掃描你的項目，找到你全部模塊，產生stub 文件。

Sphnix默認設置爲更改則自動更新。他們有幾處信息告訴setup.py，被注入到sphinx設置中。

查看pbr 段落設置詳細信息來設置你的項目

Requirements

You may not have noticed, but there are differences in how pip requirements.txt files work and how distutils wants to be told about requirements. The pip way is nicer because it sure does make it easier to populate a virtualenv for testing or to just install everything you need. Duplicating the information, though, is super lame. To solve this issue, pbr will let you use requirements.txt-format files to describe the requirements for your project and will then parse these files, split them up appropriately, and inject them into the install_requires, tests_require and/or dependency_links arguments to setup. Voila!

You can also have a requirement file for each specific major version of Python. If you want to have a different package list for Python 3 then just drop a requirements-py3.txt and it will be used instead.

Finally, it is possible to specify groups of optional dependencies, or 「extra」 requirements, in your setup.cfg rather than setup.py.

要求

你可能沒有注意，可是pip 的requirements.txt 工做方式與 distutils的告知requirements需求是有差別的。pip方式更好，由於它保證操做virtualenv，以及安裝全部軟件更加容易，容易產生重複信息，但，很是糟糕。爲了解決這個問題，pbr會讓你使用requirements.txt-格式的文件去描述你的項目的前提需求，而後解析這些文檔，將它們恰當分割開來，而後將它們注入到 安裝需求 (install requires)，測試需求(tests require),依賴路徑的設置。真不錯。

你能夠爲特別版本的python設置需求文檔。若是你但願python 3有不一樣的安裝包列表你能夠寫一個 requirements-py3.txt，它會被使用。

最後，能夠設置可選的依賴，或者「特別」需求。在你的setup.cfg文件中。

long_description

There is no need to maintain two long descriptions- and your README file is probably a good long_description. So we’ll just inject the contents of your README.rst, README.txt or README file into your empty long_description. Yay for you.

日誌描述

沒有必要維護兩個詳細描述-你的README文件就應該是很好的描述。因此咱們將你的README.rst，或者README.txt 或者README文件中的內容提取出來，做爲項目描述。

Usage

pbr is a setuptools plugin and so to use it you must use setuptools and call setuptools.setup(). While the normal setuptools facilities are available, pbr makes it possible to express them through static data files.

使用

pbr是setuptools的插件，因此你必須使用setuptools，而後調用setuptools.setup()函數。當普通的setuptools設施可用，pbr經過靜態的數據文檔使得需求被更加清晰表達。

setup.py

pbr only requires a minimal setup.py file compared to a standard setuptools project. This is because most configuration is located in static configuration files. This minimal setup.py file should look something like this:

pbr只須要最小化的setup.py 文件，跟普通的使用setuptools的項目相比。這是由於設置都在setup.cfg裏面。setup.py文件以下。

#!/usr/bin/env python

from setuptools import setup

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

 

Note

It is necessary to specify pbr=True to enabled pbr functionality.

Note

While one can pass any arguments supported by setuptools to setup(), any conflicting arguments supplied in setup.cfg will take precedence.

注意:

必須設置pbr=True,來使用pbr.

當使用setuptools的setup函數來進行設置時，若是與位於setup.cfg中的信息產生衝突，則setup.cfg則優先。

setup.cfg

The setup.cfg file is an ini-like file that can mostly replace the setup.py file. It is based on the distutils2 setup.cfg file. A simple sample can be found in pbr‘s own setup.cfg (it uses its own machinery to install itself):

setup.cfg文檔

這個文檔像ini 文檔。它基於項目distutils2的setup.cfg文件設置。下面是一個例子(這個設置中項目使用本身的機制去安裝)

[metadata]
name = pbr
author = OpenStack Foundation
author-email = openstack-dev@lists.openstack.org
summary = OpenStack's setup automation in a reusable form
description-file = README
home-page = https://launchpad.net/pbr
license = Apache-2
classifier =
    Development Status :: 4 - Beta
        Environment :: Console
        Environment :: OpenStack
        Intended Audience :: Developers
        Intended Audience :: Information Technology
        License :: OSI Approved :: Apache Software License
        Operating System :: OS Independent
        Programming Language :: Python
keywords =
    setup
    distutils
[files]
packages =
    pbr
data_files =
    etc/pbr = etc/*
    etc/init =
        pbr.packaging.conf
        pbr.version.conf
[entry_points]
console_scripts =
    pbr = pbr.cmd:main
pbr.config.drivers =
    plain = pbr.cfg.driver:Plain

 

There are a number of sections in these documents. These are:

• metadata
• files
• entry_points
• pbr

setup.cfg文件中有幾個段落：

• metadata
• files
• entry_points
• pbr

 

files

The files section defines the install location of files in the package using three fundamental keys: packages, namespace_packages, and data_files.

packages is a list of top-level packages that should be installed. The behavior of packages is similar to setuptools.find_packages in that it recurses the python package hierarchy below the given top level and installs all of it. If packages is not specified, it defaults to the value of the name field given in the [metadata] section.

namespace_packages is the same, but is a list of packages that provide namespace packages.

data_files lists files to be installed. The format is an indented block that contains key value pairs which specify target directory and source file to install there. More than one source file for a directory may be indicated with a further indented list. Source files are stripped of leading directories. Additionally, pbr supports a simple file globbing syntax for installing entire directory structures, thus:

段落 files

files段落定義了包中的文件位置，有三個基本的設置鍵：packages,namespace_packages,以及data_files.

packages指定了必須安裝的數個最高級別的包的列表。這個像setuptools中的函數find_packages.這裏面它進入python的包體系中，在最高的級別路徑下安裝它。若是packages沒有被指明，則默認爲metadata段落中的name鍵值。

[files]
data_files =
    etc/pbr = etc/pbr/*
    etc/neutron =
        etc/api-paste.ini
        etc/dhcp-agent.ini
    etc/init.d = neutron.init

 

will result in /etc/neutron containing api-paste.ini and dhcp-agent.ini, both of which pbr will expect to find in the etc directory in the root of the source tree. Additionally, neutron.init from that dir will be installed in /etc/init.d. All of the files and directories located under etc/pbr in the source tree will be installed into /etc/pbr.

Note that this behavior is relative to the effective root of the environment into which the packages are installed, so depending on available permissions this could be the actual system-wide /etc directory or just a top-level etc subdirectory of a virtualenv.

上面的配置會 將本項目的etc/api-paste.ini拷貝/etc/neutron 文件夾中，而將項目中的etc/pbr中的全部文件拷貝到/etc/pbr中。項目中的neutron.init將會拷貝到/etc/init.d中。

注意:

這種行爲是根據在那個環境下包被安裝，以及它們相應的根目錄。(也就是說拷貝也許不是到/etc/neutron中，或者某個子目錄下面的etc/neutron中)。因此基於權限，文件會被拷貝到根目錄下的etc或者某個子目錄下的etc

entry_points

The entry_points section defines entry points for generated console scripts and python libraries.

The general syntax of specifying entry points is a top level name indicating the entry point group name, followed by one or more key value pairs naming the entry point to be installed. For instance:

段落entry_points

這個段落定義了命令行命令以及python的庫lib的進入點。

裏面的內容分紅子段落，子段落的頭行設置了一組進入點的最高級目錄的名稱，裏面定義了鍵值對，描述了會被安裝的進入點。

[entry_points]
console_scripts =
    pbr = pbr.cmd:main
pbr.config.drivers =
    plain = pbr.cfg.driver:Plain
    fancy = pbr.cfg.driver:Fancy

 

Will cause a console script called pbr to be installed that executes the main function found in pbr.cmd. Additionally, two entry points will be installed for pbr.config.drivers, one called plain which maps to the Plain class in pbr.cfg.driver and one called fancy which maps to the Fancy class in pbr.cfg.driver.

這段設置會產生一個pbr的腳本，執行pbr.cmd中的main函數，而pbr.config.dirvers則會安裝兩個進入點，爲plain以及fancy。對應Plain,和Fancy函數。

pbr

The pbr section controls pbr specific options and behaviours.

The autodoc_tree_index_modules is a boolean option controlling whether pbr should generate an index of modules using sphinx-apidoc. By default, setup.py is excluded. The list of excluded modules can be specified with the autodoc_tree_excludes option. See the sphinx-apidoc man page for more information.

The autodoc_index_modules is a boolean option controlling whether pbr should itself generates documentation for Python modules of the project. By default, all found Python modules are included; some of them can be excluded by listing them in autodoc_exclude_modules. This list of modules can contains fnmatch style pattern (e.g. myapp.tests.*) to exclude some modules.

The warnerrors boolean option is used to tell Sphinx builders to treat warnings as errors which will cause sphinx-build to fail if it encounters warnings. This is generally useful to ensure your documentation stays clean once you have a good docs build.

pbr

pbr段落控制pbr相關的參數以及行爲

autodoct_tree_index_modules 是一個布爾型參數，描述pbr是否應該爲sphinx-apidoc中的模塊自動產生索引。默認的，setup.py排除在外。能夠在autodoc_tree-excludes的設置中設定一系列被排除在外的模塊。參考sphinx-apidoc man page 獲取更多幫助信息。

autodoc_index_modules是一個布爾型參數,控制pbr是否本身爲項目的python模塊產生文檔。默認的，因此找到的python模塊包含在內；他們有些被autodoc_exclude_modules排除掉了。這個排除文件模塊列表能夠包含fnmatch 風格的設置(例如myapp.tests.*) 

warnerrors 是一個布爾型參數，用來告訴sphinx 將警告信息看待爲出錯信息，若是當它遇到警告就會失敗。若是你想讓你的文檔乾淨良好這樣作很必要。

Note

When using autodoc_tree_excludes or autodoc_index_modules you may also need to set exclude_patterns in your Sphinx configuration file (generally found at doc/source/conf.py in most OpenStack projects) otherwise Sphinx may complain about documents that are not in a toctree. This is especially true if the warnerrors=True option is set. See the Sphinx build configuration file documentation for more information on configuring Sphinx.

注意

當使用autodoc_tree_excludes 或者autodoc_index_modules。你也須要在sphinx的配置文件中設置exclude_patterns(通常在項目中的 /doc/source/conf.py找到)。不然sphinx將會告知文檔不在toctree中。當warnerrors=True開啓後這個也須要爲真。參考Sphinx build configuration file 文檔獲取更多如何配置sphinx.

 

Comments

Comments may be used in setup.cfg, however all comments should start with a # and may be on a single line, or in line, with at least one white space character immediately preceding the #. Semicolons are not a supported comment delimiter. For instance:

評論

段落能夠設置評論，必須以#開頭，#後面緊跟一個空格。

[section]
# A comment at the start of a dedicated line
key =
    value1 # An in line comment
    value2
    # A comment on a dedicated line
    value3

 

Requirements

Requirement files should be given one of the below names. This order is also the order that the requirements are tried in (where N is the Python major version number used to install the package):

• requirements-pyN.txt
• tools/pip-requires-py3
• requirements.txt
• tools/pip-requires

Only the first file found is used to install the list of packages it contains.

Note

The ‘requirements-pyN.txt’ file is deprecated - ‘requirements.txt’ should be universal. You can use Environment markers for this purpose.

項目需求

需求文檔必須以如下名字命名。列舉順序也就是python進行嘗試時候的順序。(這裏面N表明python安裝包時候的主要版本數字)

• requirements-pyN.txt
• tools/pip-requires-py3
• requirements.txt
• tools/pip-requires

僅僅第一個文件用來安裝全部包

注意

'requirements-pyN.txt'文件不被建議，而‘requirements.txt’是通用格式，你能夠參考Environment markers 查看。

Extra requirements

Groups of optional dependencies, or 「extra」 requirements, can be described in your setup.cfg, rather than needing to be added to setup.py. An example (which also demonstrates the use of environment markers) is shown below.

其餘的需求

一組可選的依賴，或者‘額外’的依賴，與其在setup.py中，也能夠在setup.cfg中被描述。下面就是一個例子(展現了環境標籤的使用)

Environment markers

Environment markers are conditional dependencies which can be added to the requirements (or to a group of extra requirements) automatically, depending on the environment the installer is running in. They can be added to requirements in the requirements file, or to extras defined in setup.cfg, but the format is slightly different for each.

環境標籤

環境標籤是條件依賴，根據運行環境來設定需求文件。它們能夠被加入進requirements文檔或者在setup.cfg中定義,可是格式有些微不一樣。

For requirements.txt:

argparse; python_version=='2.6'
 

例如在requirements.txt中

argparse; python_version=='2.6'

This will result in the package depending on argparse only if it’s being installed into Python 2.6

For extras specifed in setup.cfg, add an extras section. For instance, to create two groups of extra requirements with additional constraints on the environment, you can use:

這會致使包依賴於argparse包，僅僅當在python2.6的狀況下

而在setup.cfg中，在extras段裏面，例如，建立依賴環境的兩個需求組，你可使用如下配置：

[extras]
security =
    aleph
    bet:python_version=='3.2'
    gimel:python_version=='2.7'
testing =
    quux:python_version=='2.7'