Packaging Python has been a painful experience for long. The history of the various distribution 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 the recent years, with the reconciliation of setuptools and distribute.
Though in the context of the OpenStack project, a solution on top of setuptools has been 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.
How it works
pbr takes inspiration from distutils2 (a now abandoned project) and uses a
setup.cfg file to describe the packager's intents. This is how a
using pbr looks like:
Two lines of code – it's that simple. The actual metadata that the setup requires is stored in
name = foobar
author = Dave Null
author-email = email@example.com
summary = Package doing nifty stuff
license = MIT
home-page = http://pypi.python.org/pypi/foobar
requires-python = >=2.6
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
This syntax is way easier to write and read than the standard
pbr also offers other features such as:
- automatic dependency installation based on
- automatic documentation building and generation using Sphinx
- automatic generation of
ChangeLogfiles 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.
One of the feature 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 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.
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:
When installing your package, the user can then just pick the right flavor by using pip to install the package:
$ pip install foobar[postgresql]
This will install foobar, all its dependencies listed in
plus whatever dependencies are listed in the
[extras] section of
matching the flavor. You can also combine several flavors, e.g.:
$ pip install foobar[postgresql,mysql]
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.