Paver: Easy Scripting for Software Projects

Japanese translation available thanks to Tetsuya Morimoto. Latest stable documentation is on PyPI, latest development docs are on github pages

Paver is a Python-based software project scripting tool along the lines of Make or Rake. It is not designed to handle the dependency tracking requirements of, for example, a C program. It is designed to help out with all of your other repetitive tasks (run documentation generators, moving files around, downloading things), all with the convenience of Python’s syntax and massive library of code.

If you’re developing applications in Python, you get even more... Most public Python projects use distutils or setuptools to create source tarballs for distribution. (Private projects can take advantage of this, too!) Have you ever wanted to generate the docs before building the source distribution? With Paver, you can, trivially. Here’s a complete pavement.py:

from paver.easy import *
from paver.setuputils import setup

setup(
    name="MyCoolProject",
    packages=['mycool'],
    version="1.0",
    url="http://www.blueskyonmars.com/",
    author="Kevin Dangoor",
    author_email="dangoor@gmail.com"
)

@task
@needs(['html', "distutils.command.sdist"])
def sdist():
    """Generate docs and source distribution."""
    pass

With that pavement file, you can just run paver sdist, and your docs will be rebuilt automatically before creating the source distribution. It’s also easy to move the generated docs into some other directory (and, of course, you can tell Paver where your docs are stored, if they’re not in the default location.)

Features

• Build files are just Python
• One file with one syntax, pavement.py, knows how to manage your project
• File operations are unbelievably easy, thanks to the built-in version of Jason Orendorff’s path.py.
• Need to do something that takes 5 lines of code? It’ll only take 5 lines of code..
• Completely encompasses distutils and setuptools so that you can customize behavior as you need to.
• Wraps Sphinx for generating documentation, and adds utilities that make it easier to incorporate fully tested sample code.
• Wraps Subversion for working with code that is checked out.
• Wraps virtualenv to allow you to trivially create a bootstrap script that gets a virtual environment up and running. This is a great way to install packages into a contained environment.
• Can use all of these other libraries, but requires none of them
• Easily transition from setup.py without making your users learn about or even install Paver! (See the Getting Started Guide for an example).

See how it works! Check out the Getting Started Guide.

Paver was created by Kevin Dangoor of SitePen.

Status

Paver has been in use in production settings since mid-2008, and significant attention is paid to backwards compatibility since the release of 1.0.

See the changelog for more information about recent improvements.

Installation

The easiest way to get Paver is if you have setuptools installed.

easy_install Paver

Without setuptools, it’s still pretty easy. Download the Paver .tgz file from Paver’s Cheeseshop page, untar it and run:

python setup.py install

Help and Development

You can get help from the mailing list.

If you’d like to help out with Paver, you can check the code out from github:

git clone https://github.com/paver/paver.git

Ideally, create a fork, fix an issue from Paver’s list of issues (or create an issue Yourself) and send a pull request.

Your help is appreciated!

Running test suite

Paver contains both unit and integration test suite. Unittests are run by either paver test or paver unit. Integration tests can be run by paver integrate.

Using older, system-wide installed paver to run tests on development version can lead to bad interactions (see issue 33). Please, run paver test suite using development version itself, by:

• Creating virtual environment with –no-site-packages

and

• Installing development version with python setup.py develop

or

• Using embedded minilib, thus invoking commands with setup.py instead of paver

License

Paver is licensed under a BSD license. See the LICENSE.txt file in the distribution.

Contents

• Foreword: Why Paver?
  • The Declarative/Imperative Divide
  • Consistency for Project Related Tasks
  • That’s Why Paver Is Here
  • Making the Switch is Easy
• Paver’s Features
  • Files Are Just Python
  • One File with One Syntax
  • Easy file operations
  • Small bits of behavior take small amounts of work
  • Can Take Advantage of Libraries But Doesn’t Require Them
• Getting Started with Paver
  • The Old Way
  • The New Way
• pavement.py in depth
  • Defining Tasks
  • Manually Calling Tasks
  • How Task Names Work
  • Task Parameters
  • Command Line Arguments
  • Hiding tasks
  • More complex dependencies
• The Paver Standard Library
  • distutils and setuptools (paver.setuputils)
  • File Handling in Paver (paver.path)
  • Documentation Tools (paver.doctools)
  • Miscellaneous Tasks (paver.misctasks)
  • Virtualenv Support (paver.virtual)
  • Using virtualenv with tasks
  • paver.virtual Tasks
  • Using with Subversion (paver.svn)
  • Using with Bazaar-NG (bzr) (paver.bzr)
  • SSH Remote Access Support (paver.ssh)
• Paver Command Line
• Tips and Tricks
  • Using a Config File For Settings
• Articles about Paver
• Paver Changelog
  • 1.1.0 (July 30, 2012)
  • 1.0.5 (October 21, 2011)
  • 1.0.4 (January 16, 2011)
  • 1.0.3 (June 1, 2010)
  • 1.0.2 (March 8, 2010)
  • 1.0.1 (May 4, 2009)
  • 1.0 (March 22, 2009)
  • 1.0b1 (March 13, 2009)
  • 1.0a4 (March 6, 2009)
  • 1.0a3 (March 6, 2009)
  • 1.0a2 (February 26, 2009)
  • 1.0a1 (January 28, 2009)
  • 0.8.1 (June 2, 2008)
  • 0.8 (May 19, 2008)
  • 0.7.3 (May 16, 2008)
  • 0.7.2 (May 8, 2008)
  • 0.7.1 (May 8, 2008)
  • 0.7 (May 7, 2008)
  • 0.4 (April 22, 2008)
• Credits

Indices and tables

• Index
• Module Index
• Search Page