Usage¶

files¶

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

packages

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

Similar to packages, but is a list of packages that provide namespace packages.

data_files

A list of 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. For example:

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

This 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 directory 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.

entry_points¶

The entry_points section defines entry points for generated console scripts and Python libraries. This is actually provided by setuptools but is documented here owing to its importance.

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]
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.

backwards_compat¶

pbr¶

The pbr section controls pbr-specific options and behaviours.

skip_git_sdist

If enabled, pbr will not generate a manifest file from git commits. If this is enabled, you may need to define your own manifest template.

This can also be configured using the SKIP_GIT_SDIST environment variable, as described here.

skip_changelog

If enabled, pbr will not generated a ChangeLog file from git commits.

This can also be configured using the SKIP_WRITE_GIT_CHANGELOG environment variable, as described here

skip_authors

If enabled, pbr will not generate an AUTHORS file from git commits.

This can also be configured using the SKIP_GENERATE_AUTHORS environment variable, as described here

skip_reno

If enabled, pbr will not generate a RELEASENOTES.txt file if reno is present and configured.

This can also be configured using the SKIP_GENERATE_RENO environment variable, as described here.

autodoc_tree_index_modules

A boolean option controlling whether pbr should generate an index of modules using sphinx-apidoc. By default, all files except setup.py are included, but this can be overridden using the autodoc_tree_excludes option.

Deprecated since version 4.2: This feature has been replaced by the sphinxcontrib-apidoc extension. Refer to the build_sphinx overview for more information.

autodoc_tree_excludes

A list of modules to exclude when building documentation using sphinx-apidoc. Defaults to [setup.py]. Refer to the sphinx-apidoc man page for more information.

Deprecated since version 4.2: This feature has been replaced by the sphinxcontrib-apidoc extension. Refer to the build_sphinx overview for more information.

autodoc_index_modules

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.

Deprecated since version 4.2: This feature has been replaced by the sphinxcontrib-apidoc extension. Refer to the build_sphinx overview for more information.

autodoc_exclude_modules

A list of modules to exclude when building module documentation using pbr. fnmatch style pattern (e.g. myapp.tests.*) can be used.

Deprecated since version 4.2: This feature has been replaced by the sphinxcontrib-apidoc extension. Refer to the build_sphinx overview for more information.

api_doc_dir

A subdirectory inside the build_sphinx.source_dir where auto-generated API documentation should be written, if autodoc_index_modules is set to True. Defaults to "api".

Deprecated since version 4.2: This feature has been replaced by the sphinxcontrib-apidoc extension. Refer to the build_sphinx overview for more information.

metadata¶

build_sphinx¶

The build_sphinx section is a version of the build_sphinx setuptools plugin provided with Sphinx. This plugin extends the original plugin to add the following:

• Automatic generation of module documentation using the sphinx-apidoc tool

• Automatic configuration of the project, version and release settings using information from pbr itself

• Support for multiple builders using the builders configuration option

  Note

  Only applies to Sphinx < 1.6. See documentation on builders below.

The version of build_sphinx provided by pbr provides a single additional option.

builders

A comma separated list of builders to run. For example, to build both HTML and man page documentation, you would define the following in your setup.cfg:

[build_sphinx]
builders = html,man
source-dir = doc/source
build-dir = doc/build
all-files = 1
warning-is-error = 1

Deprecated since version 3.2.0: Sphinx 1.6+ adds support for specifying multiple builders in the default builder option. You should use this option instead. Refer to the Sphinx documentation for more information.

For information on the remaining options, refer to the Sphinx documentation. In addition, the autodoc_index_modules, autodoc_tree_index_modules, autodoc_exclude_modules and autodoc_tree_excludes options in the pbr section will affect the output of the automatic module documentation generation.

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.

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.

For 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 specified 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:

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