Over a million developers have joined DZone.

Packaging Python Software With Pbr

DZone's Guide to

Packaging Python Software With Pbr

Is pbr the end to Python packaging woes? If you're considering working with distributed software, this tool can help you manage flavors, and more, with ease.

· Cloud Zone ·
Free Resource

Learn how to migrate and modernize stateless applications and run them in a Kubernetes cluster.

Packaging Python has been a painful experience for a long time. The history of the various distributions that Python offered along the years is really bumpy, and both the user and developer experience has been pretty bad.

Fortunately, things improved a lot in recent years, with the reconciliation of setuptools and distribute.

Though in the context of the OpenStack project, a solution on top of setuptools was already started a while back. Its usage is now spread across a whole range of software and libraries.

This project is called pbr, for Python Build Reasonableness. Don't be afraid by the OpenStack colored themed of the documentation — it is a bad habit of OpenStack folks to not advertise their tooling in an agnostic fashion. The tool has no dependency with the cloud platform and can be used painlessly with any package.

Pbr takes its inspiration from distutils2 (a now abandoned project) and uses a setup.cfg file to describe the packager's intents. This is how a setup.py using pbr looks like:

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

 Two lines of code – it's that simple. The actual metadata that the setup requires is stored in setup.cfg:

name = foobar
author = Dave Null
author-email = foobar@example.org
summary = Package doing nifty stuff
license = MIT
description-file =
home-page = http://pypi.python.org/pypi/foobar
requires-python = >=2.6
classifier = 
    Development Status :: 4 - Beta
    Environment :: Console
    Intended Audience :: Developers
    Intended Audience :: Information Technology
    License :: OSI Approved :: Apache Software License
    Operating System :: OS Independent
    Programming Language :: Python [files]
packages =

This syntax is way easier to write and read than the standard setup.py.

Pbr also offers other features, such as:

  • Automatic dependency installation based on requirements.txt
  • Automatic documentation building and generation using Sphinx.
  • Automatic generation of AUTHORS and ChangeLog files based on git history.
  • Automatic creation of the list of files to include using git.
  • Version management based on git tags.

All of this comes with little to no effort on your part.

Using Flavors

One of the features that I use a lot, is the definition of flavors. It's not tied particularly to pbr—it's actually provided by setuptools and pip themselves—but the pbr setup.cfg file makes it easy to use.

When distributing a software, it's common to have different drivers for it. For example, your project could support both PostgreSQL or MySQL—but nobody is going to use both at the same time. The usual trick to make it work is to add the needed library to the requirements list (e.g. requirements.txt). The upside is that the software will work directly with either RDBMS, but the downside is that this will install both libraries, whereas only one is needed. Using flavors, you can specify different scenarios:

postgresql =
mysql =

When installing your package, the user can then just pick the right flavor by using pip to install it:

$ pip install foobar[postgresql]

This will install foobar, all its dependencies listed in requirements.txt, plus whatever dependencies are listed in the [extras] section of setup.cfg matching the flavor. You can also combine several flavors, e.g.:

$ pip install foobar[postgresql,mysql]

If desired, that code would install both flavors.

Pbr is well-maintained and in very active development, so if you have any plans to distribute your software, you should seriously consider including pbr in those plans.

Join us in exploring application and infrastructure changes required for running scalable, observable, and portable apps on Kubernetes.

python ,pbr ,cloud ,distributed development ,tutorial

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}