To understand what pbr can do for you, it’s probably best to look at two projects: one using pure setuptools, and another using pbr. First, let’s look at the setuptools project.
$ tree -L 1 . ├── AUTHORS ├── CHANGES ├── LICENSE ├── MANIFEST.in ├── README.rst ├── requirements.txt ├── setup.cfg ├── setup.py └── somepackage $ cat setup.py setuptools.setup( name='mypackage', version='1.0.0', description='A short description', long_description="""A much longer description...""", author="John Doe", firstname.lastname@example.org', license='BSD', )
Here’s a similar package using pbr:
$ tree -L 1 . ├── LICENSE ├── README.rst ├── setup.cfg ├── setup.py └── somepackage $ cat setup.py setuptools.setup( pbr=True ) $ cat setup.cfg [metadata] name = mypackage description = A short description description-file = README.rst author = John Doe author-email = email@example.com license = BSD
From this, we note a couple of the main features of pbr:
Extensive use of
Automatic package metadata generation (
Automatic metadata file generation (
In addition, there are other things that you don’t see here but which pbr will do for you:
Helpful extensions to setuptools commands
setup.cfg for all configuration, though
One of the main features of distutils2 was the use of a
INI-style configuration file. This was used to define a package’s metadata and
other options that were normally supplied to the
Recent versions of setuptools have implemented some of this support, but
pbr still allows for the definition of the following sections in
For more information on these sections, refer to Usage.
pbr removes the need to define a lot of configuration in either
setup.cfg by extracting this information from Git.
pbr will automatically configure your version for you by parsing semantically-versioned Git tags.
Versions can be managed two ways - post-versioning and pre-versioning.
Post-versioning is the default while pre-versioning is enabled by setting
version in the
metadata section. In both cases the actual
version strings are inferred from Git.
If the currently checked out revision is tagged, that tag is used as the version.
If the currently checked out revision is not tagged, then we take the last tagged version number and increment it to get a minimum target version.
pbr supports both bare version tag (e.g.
0.1.0) and version prefixed
We then walk Git history back to the last release. Within each commit we look
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. The following symbols
Sem-Ver line is equivalent to
Sem-Ver: bugfix. The
symbol causes a patch level increment to the version. The
deprecation symbols cause a minor version increment. The
symbol causes a major version increment.
If post-versioning is in use, we use the resulting version number as the target version.
If pre-versioning is in use, we check that the version set in the metadata
setup.cfg is greater than the version we infer using the above
method. If the inferred version is greater than the pre-versioning value 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.
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.
version.SemanticVersion class can be used to query versions of a
package and present it in various forms -
pbr can extract the contents of a
README and use this as your long
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 file into your empty
You can also specify the exact file you want to use using the
You can set the
description-content-type to a MIME type that may
help rendering of the description; for example
pbr will extract requirements from
requirements.txt files and
automatically populate the
dependency_links arguments to
setup with them.
You may not have noticed, but there are differences in how pip
requirements.txt files work and how setuptools 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
dependency_links arguments to
Finally, it is possible to specify groups of optional dependencies, or
“extra” requirements, in your
Changed in version 5.0: Previously you could specify requirements for a given major version of
Python using requirments files with a
-pyN suffix. This was deprecated
in 4.0 and removed in 5.0 in favour of environment markers.
Automatic File Generation¶
pbr can automatically generate a couple of files, which would normally have to be maintained manually, by using Git data.
pbr will automatically generate a
MANIFEST.in file based on the files
Git is tracking.
ChangeLog, why keep a list of files you wish to
include when you can find many of these in Git.
ensures almost all files stored in Git, with the exception of
.pyc files, are automatically included in your
distribution. In addition, the generated
are also included. In many cases, this removes the need for an explicit
MANIFEST.in file, though one can be provided to exclude files that are
tracked via Git but which should not be included in the final release, such as
MANIFEST.in files have no effect on binary distributions such as wheels.
Refer to the Python packaging tutorial for more information.
pbr will automatically use reno 's
build_reno setuptools command
to generate a release notes file, if reno is available and configured.
If using reno, you may wish to include a copy of the release notes in your
packages. reno provides a
build_reno setuptools command and, if reno
is present and configured, pbr will automatically call this to generate a
release notes file for inclusion in your package.
pbr will override the Sphinx
build_sphinx command to use
pbr-provided package metadata and automatically generate API
Deprecated since version 4.2: This feature has been superseded by the sphinxcontrib-apidoc (for generation of API documentation) and Sphinx Extension (for configuration of versioning via package metadata) extensions. It will be removed in a future release.
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.
In addition, Sphinx documentation setups are altered to have several pieces of
information that are known to
setup.py injected into the Sphinx config.
See the pbr section of the configuration file for details on configuring your project for autodoc.
pbr will automatically alias the
test command to use the testing tool
of your choice.
Deprecated since version 4.0.
pbr will check for a
.testr.conffile. If this exists and testrepository is installed, the
testcommand will alias the testr test runner. If this is not the case…
This is separate to
setup.py testr(note the extra
r) which is provided directly by the
testrepositorypackage. Be careful as there is some overlap of command arguments.
pbr will check if
[nosetests]is defined in
setup.cfg. If this exists and nose is installed, the
testcommand will alias the nose runner. If this is not the case…
In other cases no override will be installed and the
testcommand will revert to the setuptools default.
pbr provides a Sphinx extension to allow you to use pbr version metadata in your Sphinx documentation.
New in version 4.2.
pbr provides a Sphinx extension which can be used to configure version numbers for documentation. The package does not need to be installed for this to function.
openstackdocstheme Sphinx theme provides similar functionality.
This should be preferred for official OpenStack projects. Refer to the
documentation for more information.
For more information on the extension, refer to Usage.