Foreword: Why Paver?

Paver occupies a sweet spot in the python toolset, the design is sound, it’s easier than mud to work with at a basic level, and it has a nice grade of descent into more advanced things.

—David Eyk

I didn’t want to make a new build tool. Honestly. The main reason that I created Paver is...

The Declarative/Imperative Divide

When you solve the same problem repeatedly, patterns emerge and you’re able to easily see ways to reduce how much effort is involved in solving that problem. Often times, you’ll end up with a declarative solution. Python’s standard distutils is a declarative solution. In your call to the setup() function, you declare some metadata about your project and provide a list of the parts and you end up with a nice command line interface. That command line interface knows how to make redistributable tarballs (and eggs if you have setuptools), install the package, build C extensions and more.

zc.buildout does a similar thing for deployments. Declare the parts of your system and specify a recipe for each part (each recipe with its own collection of options) and you can build up a consistent system with one command.

These tools sound great, don’t they? They are great. As long as you don’t need to customize the capabilities they provide. For example, it’s not uncommon that you’ll need to move some file here, create some directory there, etc. Then what?

In an imperative system, you’d just add the few lines of code you need.

For distutils and zc.builout and other similar tools, the answer usually involves extra boilerplate surrounding the code in question and then installing that code somewhere. You basically have to create declarative syntax for something that is a one-off rather than a larger, well-understood problem. And, for distutils and zc.buildout, you have to use two entirely different mechanisms.

That’s Why Paver Is Here

Paver is set up to provide declarative handling of common tasks with as easy an escape hatch to imperative programming as possible (just add a function with a decorator in the same file). Your project-related configuration options are all together and all accessible to different parts of your build and deployment setup. And the language used for everything is Python, so you’re not left guessing how to do a for loop.

Of course, rebuilding the great infrastructure provided by tools like distutils makes no sense. So, Paver just uses distutils and other tools directly.

Paver also goes beyond just providing an extension mechanism for distutils. It adds a bunch of useful capabilities for things like working with files and directories, elegantly handling sample code for your documentation and building bootstrap scripts to allow your software to easily be installed in an isolated virtualenv.

I’m already using Paver for SitePen’s Support service user interface project and I use Paver to manage Paver itself! It’s been working out great for me, and it’s set up in such a way that whatever kind of scripting your project needs it should be pretty simple with Paver.

Making the Switch is Easy

Finally, I’ve put some time into making sure that moving a project from distutils to Paver is easy for everyone involved (people making the projects and people using the projects). Check out the Getting Started Guide to see an example of how a project moves from distutils to Paver (even maintaining the python setup.py install command that everyone’s used to!)

Thanks for reading!

Kevin Dangoor May 2008