paver package

Submodules

paver.bzr module

paver.command module

Paver’s command-line driver

paver.command.main()

paver.defaults module

The namespace for the pavement to run in, also imports default tasks.

paver.doctools module

Tasks and utility functions and classes for working with project documentation.

class paver.doctools.Includer(basedir, cog=None, include_markers=None)

Bases: object

Looks up SectionedFiles relative to the basedir.

When called with a filename and an optional section, the Includer will:

  1. look up that file relative to the basedir in a cache
  2. load it as a SectionedFile if it’s not in the cache
  3. return the whole file if section is None
  4. return just the section desired if a section is requested

If a cog object is provided at initialization, the text will be output (via cog’s out) rather than returned as a string.

You can pass in include_markers which is a dictionary that maps file extensions to the single line comment character for that file type. If there is an include marker available, then output like:

# section ‘sectionname’ from ‘file.py’

There are some default include markers. If you don’t pass in anything, no include markers will be displayed. If you pass in an empty dictionary, the default ones will be displayed.

class paver.doctools.SectionedFile(filename=None, from_string=None)

Bases: object

Loads a file into memory and keeps track of all of the sections found in the file. Sections are started with a line that looks like this:

[[[section SECTIONNAME]]]

Anything else can appear on the line outside of the brackets (so if you’re in a source code file, you can put the section marker in a comment). The entire lines containing the section markers are not included when you request the text from the file.

An end of section marker looks like this:

[[[endsection]]]

Sections can be nested. If you do nest sections, you will use dotted notation to refer to the inner sections. For example, a “dessert” section within an “order” section would be referred to as “order.dessert”.

The SectionedFile provides dictionary-style access to the sections. If you have a SectionedFile named ‘sf’, sf[sectionname] will give you back a string of that section of the file, including any inner sections. There won’t be any section markers in that string.

You can get the text of the whole file via the all property (for example, sf.all).

Section names must be unique across the file, but inner section names are kept track of by the full dotted name. So you can have a “dessert” section that is contained within two different outer sections.

Ending a section without starting one or ending the file without ending a section will yield BuildFailures.

all

Property to get access to the whole file.

keys()
paver.doctools.cog(options)

Runs the cog code generator against the files matching your specification. By default, cog will run against any .rst files in your Sphinx document root. Full documentation for Cog is here:

https://nedbatchelder.com/code/cog/

In a nutshell, you put blocks in your file that look like this:

[[[cog cog.outl(“Hi there!”) ]]] [[[end]]]

Cog will replace the space between ]]] and [[[end]]] with the generated output. In this case, Hi there!

Here are the options available for the cog task. These are looked up in the ‘cog’ options section by default. The ‘sphinx’ option set is also searched.

basedir
directory to look in for files to cog. If not set, ‘docroot’ is looked up.
pattern
file glob to look for under basedir. By default, *.rst
includedir

If you have external files to include in your documentation, setting includedir to the root of those files will put a paver.doctools.Includer in your Cog namespace as ‘include’. This lets you easily include files and sections of files. Here’s an example usage:

[[[cog include('filename_under_includedir.py', 'mysection')]]]
[[[end]]]
defines
Dictionary of objects added to your Cog namespace. (can supersede ‘include’ and ‘sh’ defined by includedir.)
beginspec
String used at the beginning of the code generation block. Default: [[[cog
endspec
String used at the end of the code generation block. Default; ]]]
endoutput
String used at the end of the generated output Default: [[[end]]]
delete_code
Remove the generator code. Note that this will mean that the files that get changed cannot be changed again since the code will be gone. Default: False
include_markers

Dictionary mapping file extensions to the single line comment marker for that file. There are some defaults. For example, ‘py’ maps to ‘# ‘. If there is a known include marker for a given file, then a comment will be displayed along the lines of:

# section ‘SECTIONNAME’ in file ‘foo.py’

If this option is not set, these lines will not be displayed at all. If this option is set to an empty dictionary, the default include markers will be displayed. You can also pass in your own extension -> include marker settings.

paver.doctools.doc_clean()

Clean (delete) the built docs. Specifically, this deletes the build directory under the docroot. See the html task for the options list.

paver.doctools.html()

Build HTML documentation using Sphinx. This uses the following options in a “sphinx” section of the options.

docroot
the root under which Sphinx will be working. Default: docs
builddir
directory under the docroot where the resulting files are put. default: .build
sourcedir
directory under the docroot for the source files default: (empty string)
apidir
directory under the sourcedir for the auto-generated API docs (empty = don’t create them) default: api
paver.doctools.uncog(options)

Remove the Cog generated code from files. Often, you will want to do this before committing code under source control, because you don’t generally want generated code in your version control system.

This takes the same options as the cog task. Look there for more information.

paver.easy module

paver.easy.call_task
paver.easy.debug(message, *args)

Displays a message to the user, but only if the verbose flag is set.

paver.easy.dry(message, func, *args, **kw)

Wraps a function that performs a destructive operation, so that nothing will happen when a dry run is requested.

Runs func with the given arguments and keyword arguments. If this is a dry run, print the message rather than running the function.

paver.easy.error(message, *args)

Displays an error message to the user.

paver.easy.info(message, *args)

Displays a message to the user. If the quiet option is specified, the message will not be displayed.

paver.git module

Convenience functions for working with git.

This module does not include any tasks, only functions.

At this point, these functions do not use any kind of library. They require the git binary on the path.

paver.git.branch_checkout(branch_name, path='')

Checkout a git branch.

Take the branch name to checkout, and optional path parameter (the path to the git repo. Else uses os.getcwd())

paver.git.branch_list(path='', remote_branches_only=False, __override__=None)

Lists git branches for the repository specified (or CWD). If remote_branches_only is specified will list branches that exist on the remote. These branches may, or may not, have corresponding remote tracking branches.

Returns a Python tuple. The first item in the tuple will be the current branch, and the other item will be a list of branches for the repository.

Optional parameter path: the path to the git repo. Else uses os.getcwd()

paver.git.branch_track_remote(remote_branch_name, local_branch_name=None, path='')
paver.git.clone(url, dest_folder)
paver.git.latest_tag()

Get the most recent git tag. Useful for using in package version.

paver.git.pull(destination, remote='origin', branch='master')

Perform a git pull. Destination must be absolute path.

paver.hg module

Convenience functions for working with mercurial

This module does not include any tasks, only functions.

At this point, these functions do not use any kind of library. They require the hg binary on the PATH.

paver.hg.branches(repo_path, closed=False)

List branches for the target repository.

Parameters:

repo_path (string): The local path to a mercurial repository. closed=False (bool): Whether to include closed branches in the

branch list.
Returns:
A python tuple. The first item of the tuple is the current branch. The second item of the tuple is a list of the branches
paver.hg.clone(url, dest_folder, rev=None)

Clone a mercurial repository.

Parameters:
url (string): The path to clone the repository from. Could be local
or remote.
dest_folder (string): The local folder where the repository will be
cloned.
rev=None (string or None): If specified, the revision to clone to.
If omitted or None, all changes will be cloned.
Returns:
None
paver.hg.latest_tag(repo_path, relative_to='tip')

Get the latest tag from a mercurial repository.

Parameters:

repo_path (string): The local path to a mercurial repository. relative_to=’tip’ (string): If provided, the revision to use as

a reference. Defaults to ‘tip’.
Returns:
The string name of the latest tag.
paver.hg.pull(repo_path, rev=None, url=None)

Pull changes into a mercurial repository.

Parameters:

repo_path (string): The local path to a mercurial repository. rev=None (string or None): If specified, the revision to pull to.

If omitted or None, all changes will be pulled.
url=None (string or None): If specified, the repository to pull from.
If omitted or None, the default location of the repository will be used.
Returns:
None
paver.hg.update(repo_path, rev='tip', clean=False)

Update a mercurial repository to a revision.

Parameters:

repo_path (string): The local path to a mercurial repository. rev=’tip’ (string): If provided, the revision to update to. If

omitted, ‘tip’ will be used.
clean=False (bool): If True, the update will discard uncommitted
changes.
Returns:
None

paver.misctasks module

Miscellaneous tasks that don’t fit into one of the other groupings.

paver.misctasks.generate_setup(options)

Generates a setup.py file that uses paver behind the scenes. This setup.py file will look in the directory that the user is running it in for a paver-minilib.zip and will add that to sys.path if available. Otherwise, it will just assume that paver is available.

paver.misctasks.minilib(options)

Create a Paver mini library that contains enough for a simple pavement.py to be installed using a generated setup.py. This is a good temporary measure until more people have deployed paver. The output file is ‘paver-minilib.zip’ in the current directory.

Options:

versioned_name
if set to True, paver version will be added into minilib’s filename (ie paver-minilib-1.1.0.zip) purpose is to avoid import error while using different versions of minilib with easy_install (default False)
extra_files
list of other paver modules to include (don’t include the .py extension). By default, the following modules are included: defaults, path, release, setuputils, misctasks, options, tasks, easy
extra_packages
list of unrelated packages to include. By default, Paver’s own dependencies are included. Package must be installed and importable

paver.options module

class paver.options.Bunch

Bases: dict

A dictionary that provides attribute-style access.

class paver.options.Namespace(d=None, **kw)

Bases: paver.options.Bunch

A Bunch that will search dictionaries contained within to find a value. The search order is set via the order() method. See the order method for more information about search order.

clear()
get(key, default=None)
order(*keys, **kw)

Set the search order for this namespace. The arguments should be the list of keys in the order you wish to search, or a dictionary/Bunch that you want to search. Keys that are left out will not be searched. If you pass in no arguments, then the default ordering will be used. (The default is to search the global space first, then in the order in which the sections were created.)

If you pass in a key name that is not a section, that key will be silently removed from the list.

Keyword arguments are:

add_rest=False
put the sections you list at the front of the search and add the remaining sections to the end
setdefault(key, default)
setdotted(key, value)

Sets a namespace key, value pair where the key can use dotted notation to set sub-values. For example, the key “foo.bar” will set the “bar” value in the “foo” Bunch in this Namespace. If foo does not exist, it is created as a Bunch. If foo is a value, an OptionsError will be raised.

update(d=None, **kw)

Update the namespace. This is less efficient than the standard dict.update but is necessary to keep track of the sections that we’ll be searching.

exception paver.options.OptionsError

Bases: exceptions.Exception

paver.path module

Wrapper around path.py to add dry run support and other paver integration.

class paver.path.path

Bases: paver.deps.path2.path

chdir()
chmod(*args, **kwds)
chown(*args, **kwds)
copy(*args, **kwds)

Copy data and mode bits (“cp src dst”).

The destination may be a directory.

copy2(*args, **kwds)

Copy data and all stat info (“cp -p src dst”).

The destination may be a directory.

copyfile(*args, **kwds)

Copy data from src to dst

copymode(*args, **kwds)

Copy mode bits from src to dst

copystat(*args, **kwds)

Copy all stat info (mode bits, atime, mtime, flags) from src to dst

copytree(*args, **kwds)

Recursively copy a directory tree using copy2().

The destination directory must not already exist. If exception(s) occur, an Error is raised with a list of reasons.

If the optional symlinks flag is true, symbolic links in the source tree result in symbolic links in the destination tree; if it is false, the contents of the files pointed to by symbolic links are copied.

The optional ignore argument is a callable. If given, it is called with the src parameter, which is the directory being visited by copytree(), and names which is the list of src contents, as returned by os.listdir():

callable(src, names) -> ignored_names

Since copytree() is called recursively, the callable will be called once for each directory that is copied. It returns a list of names relative to the src directory that should not be copied.

XXX Consider this example code rather than the ultimate tool.

Create a hard link at ‘newpath’, pointing to this file.

makedirs(*args, **kwds)
makedirs_p(*args, **kwds)
mkdir(*args, **kwds)
mkdir_p(*args, **kwds)
move(*args, **kwds)

Recursively move a file or directory to another location. This is similar to the Unix “mv” command.

If the destination is a directory or a symlink to a directory, the source is moved inside the directory. The destination path must not already exist.

If the destination already exists but is not a directory, it may be overwritten depending on os.rename() semantics.

If the destination is on our current filesystem, then rename() is used. Otherwise, src is copied to the destination and then removed. A lot more could be done here… A look at a mv.c shows a lot of the issues this implementation glosses over.

remove(*args, **kwds)
remove_p(*args, **kwds)
removedirs(*args, **kwds)
removedirs_p(*args, **kwds)
rename(*args, **kwds)
renames(*args, **kwds)
rmdir(*args, **kwds)
rmdir_p(*args, **kwds)
rmtree(*args, **kwds)
rmtree_p(*args, **kwds)

Create a symbolic link at ‘newlink’, pointing here.

touch(*args, **kwds)

Set the access/modified times of this file to the current time. Create the file if it does not exist.

utime(*args, **kwds)

Set the access and modified times of this file.

write_bytes(*args, **kwds)

Open this file and write the given bytes to it.

Default behavior is to overwrite any existing file. Call p.write_bytes(bytes, append=True) to append instead.

write_lines(*args, **kwds)

Write the given lines of text to this file.

By default this overwrites any existing file at this path.

This puts a platform-specific newline sequence on every line. See ‘linesep’ below.

lines - A list of strings.

encoding - A Unicode encoding to use. This applies only if
‘lines’ contains any Unicode strings.
errors - How to handle errors in Unicode encoding. This
also applies only to Unicode strings.
linesep - The desired line-ending. This line-ending is
applied to every line. If a line already has any standard line ending (‘r’, ‘n’, ‘rn’, u’x85’, u’rx85’, u’u2028’), that will be stripped off and this will be used instead. The default is os.linesep, which is platform-dependent (‘rn’ on Windows, ‘n’ on Unix, etc.) Specify None to write the lines as-is, like file.writelines().

Use the keyword argument append=True to append lines to the file. The default is to overwrite the file. Warning: When you use this with Unicode data, if the encoding of the existing data in the file is different from the encoding you specify with the encoding= parameter, the result is mixed-encoding data, which can really confuse someone trying to read the file later.

write_text(*args, **kwds)

Write the given text to this file.

The default behavior is to overwrite any existing file; to append instead, use the ‘append=True’ keyword argument.

There are two differences between path.write_text() and path.write_bytes(): newline handling and Unicode handling. See below.

Parameters:

  • text - str/unicode - The text to be written.
  • encoding - str - The Unicode encoding that will be used. This is ignored if ‘text’ isn’t a Unicode string.
  • errors - str - How to handle Unicode encoding errors. Default is ‘strict’. See help(unicode.encode) for the options. This is ignored if ‘text’ isn’t a Unicode string.
  • linesep - keyword argument - str/unicode - The sequence of characters to be used to mark end-of-line. The default is os.linesep. You can also specify None; this means to leave all newlines as they are in ‘text’.
  • append - keyword argument - bool - Specifies what to do if the file already exists (True: append to the end of it; False: overwrite it.) The default is False.

— Newline handling.

write_text() converts all standard end-of-line sequences (‘n’, ‘r’, and ‘rn’) to your platform’s default end-of-line sequence (see os.linesep; on Windows, for example, the end-of-line marker is ‘rn’).

If you don’t like your platform’s default, you can override it using the ‘linesep=’ keyword argument. If you specifically want write_text() to preserve the newlines as-is, use ‘linesep=None’.

This applies to Unicode text the same as to 8-bit text, except there are three additional standard Unicode end-of-line sequences: u’x85’, u’rx85’, and u’u2028’.

(This is slightly different from when you open a file for writing with fopen(filename, “w”) in C or open(filename, ‘w’) in Python.)

— Unicode

If ‘text’ isn’t Unicode, then apart from newline handling, the bytes are written verbatim to the file. The ‘encoding’ and ‘errors’ arguments are not used and must be omitted.

If ‘text’ is Unicode, it is first converted to bytes using the specified ‘encoding’ (or the default encoding if ‘encoding’ isn’t specified). The ‘errors’ argument applies only to this conversion.

paver.path.pushd(*args, **kwds)

A context manager for stepping into a directory and automatically coming back to the previous one. The original directory is returned. Usage is like this:

from paver.easy import *

@task
def my_task():
    with pushd('new/directory') as old_dir:
        ...do stuff...

paver.release module

Release metadata for Paver.

paver.runtime module

Helper functions and data structures used by pavements.

class paver.runtime.Bunch

Bases: dict

A dictionary that provides attribute-style access.

paver.runtime.task(func)

Specifies that this function is a task.

Note that this decorator does not actually replace the function object. It just keeps track of the task and sets an is_task flag on the function object.

paver.runtime.needs(*args)

Specifies tasks upon which this task depends.

req can be a string or a list of strings with the names of the tasks. You can call this decorator multiple times and the various requirements are added on. You can also call with the requirements as a list of arguments.

The requirements are called in the order presented in the list.

paver.runtime.dry(message, func, *args, **kw)

Wraps a function that performs a destructive operation, so that nothing will happen when a dry run is requested.

Runs func with the given arguments and keyword arguments. If this is a dry run, print the message rather than running the function.

paver.runtime.error(message, *args)

Displays an error message to the user.

paver.runtime.info(message, *args)

Displays a message to the user. If the quiet option is specified, the message will not be displayed.

paver.runtime.debug(message, *args)

Displays a message to the user, but only if the verbose flag is set.

paver.runtime.call_task(task_name, options=None)

DEPRECATED. Just call the task instead.

Calls the desired task, including any tasks upon which that task depends. options is an optional dictionary that will be added to the option lookup search order.

You can always call a task directly by calling the function directly. But, if you do so the dependencies aren’t called. call_task ensures that these are called.

Note that call_task will only call the task once during a given build as long as the options remain the same. If the options are changed, the task will be called again.

paver.runtime.require_keys(keys)

GONE. There is no equivalent in Paver 1.0. Calling this will raise an exception.

A set of dotted-notation keys that must be present in the options for this task to be relevant.

paver.runtime.sh(command, capture=False, ignore_error=False, cwd=None, env=None)

Runs an external command. If capture is True, the output of the command will be captured and returned as a string. If the command has a non-zero return code raise a BuildFailure. You can pass ignore_error=True to allow non-zero return codes to be allowed to pass silently, silently into the night. If you pass cwd=’some/path’ paver will chdir to ‘some/path’ before exectuting the command.

If the dry_run option is True, the command will not actually be run.

env is a dictionary of environment variables. Refer to subprocess.Popen’s documentation for further information on this.

exception paver.runtime.BuildFailure

Bases: exceptions.Exception

Represents a problem with some part of the build’s execution.

exception paver.runtime.PavementError

Bases: exceptions.Exception

Exception that represents a problem in the pavement.py file rather than the process of running a build.

class paver.runtime.path

Bases: paver.deps.path2.path

chdir()
chmod(*args, **kwds)
chown(*args, **kwds)
copy(*args, **kwds)

Copy data and mode bits (“cp src dst”).

The destination may be a directory.

copy2(*args, **kwds)

Copy data and all stat info (“cp -p src dst”).

The destination may be a directory.

copyfile(*args, **kwds)

Copy data from src to dst

copymode(*args, **kwds)

Copy mode bits from src to dst

copystat(*args, **kwds)

Copy all stat info (mode bits, atime, mtime, flags) from src to dst

copytree(*args, **kwds)

Recursively copy a directory tree using copy2().

The destination directory must not already exist. If exception(s) occur, an Error is raised with a list of reasons.

If the optional symlinks flag is true, symbolic links in the source tree result in symbolic links in the destination tree; if it is false, the contents of the files pointed to by symbolic links are copied.

The optional ignore argument is a callable. If given, it is called with the src parameter, which is the directory being visited by copytree(), and names which is the list of src contents, as returned by os.listdir():

callable(src, names) -> ignored_names

Since copytree() is called recursively, the callable will be called once for each directory that is copied. It returns a list of names relative to the src directory that should not be copied.

XXX Consider this example code rather than the ultimate tool.

Create a hard link at ‘newpath’, pointing to this file.

makedirs(*args, **kwds)
makedirs_p(*args, **kwds)
mkdir(*args, **kwds)
mkdir_p(*args, **kwds)
move(*args, **kwds)

Recursively move a file or directory to another location. This is similar to the Unix “mv” command.

If the destination is a directory or a symlink to a directory, the source is moved inside the directory. The destination path must not already exist.

If the destination already exists but is not a directory, it may be overwritten depending on os.rename() semantics.

If the destination is on our current filesystem, then rename() is used. Otherwise, src is copied to the destination and then removed. A lot more could be done here… A look at a mv.c shows a lot of the issues this implementation glosses over.

remove(*args, **kwds)
remove_p(*args, **kwds)
removedirs(*args, **kwds)
removedirs_p(*args, **kwds)
rename(*args, **kwds)
renames(*args, **kwds)
rmdir(*args, **kwds)
rmdir_p(*args, **kwds)
rmtree(*args, **kwds)
rmtree_p(*args, **kwds)

Create a symbolic link at ‘newlink’, pointing here.

touch(*args, **kwds)

Set the access/modified times of this file to the current time. Create the file if it does not exist.

utime(*args, **kwds)

Set the access and modified times of this file.

write_bytes(*args, **kwds)

Open this file and write the given bytes to it.

Default behavior is to overwrite any existing file. Call p.write_bytes(bytes, append=True) to append instead.

write_lines(*args, **kwds)

Write the given lines of text to this file.

By default this overwrites any existing file at this path.

This puts a platform-specific newline sequence on every line. See ‘linesep’ below.

lines - A list of strings.

encoding - A Unicode encoding to use. This applies only if
‘lines’ contains any Unicode strings.
errors - How to handle errors in Unicode encoding. This
also applies only to Unicode strings.
linesep - The desired line-ending. This line-ending is
applied to every line. If a line already has any standard line ending (‘r’, ‘n’, ‘rn’, u’x85’, u’rx85’, u’u2028’), that will be stripped off and this will be used instead. The default is os.linesep, which is platform-dependent (‘rn’ on Windows, ‘n’ on Unix, etc.) Specify None to write the lines as-is, like file.writelines().

Use the keyword argument append=True to append lines to the file. The default is to overwrite the file. Warning: When you use this with Unicode data, if the encoding of the existing data in the file is different from the encoding you specify with the encoding= parameter, the result is mixed-encoding data, which can really confuse someone trying to read the file later.

write_text(*args, **kwds)

Write the given text to this file.

The default behavior is to overwrite any existing file; to append instead, use the ‘append=True’ keyword argument.

There are two differences between path.write_text() and path.write_bytes(): newline handling and Unicode handling. See below.

Parameters:

  • text - str/unicode - The text to be written.
  • encoding - str - The Unicode encoding that will be used. This is ignored if ‘text’ isn’t a Unicode string.
  • errors - str - How to handle Unicode encoding errors. Default is ‘strict’. See help(unicode.encode) for the options. This is ignored if ‘text’ isn’t a Unicode string.
  • linesep - keyword argument - str/unicode - The sequence of characters to be used to mark end-of-line. The default is os.linesep. You can also specify None; this means to leave all newlines as they are in ‘text’.
  • append - keyword argument - bool - Specifies what to do if the file already exists (True: append to the end of it; False: overwrite it.) The default is False.

— Newline handling.

write_text() converts all standard end-of-line sequences (‘n’, ‘r’, and ‘rn’) to your platform’s default end-of-line sequence (see os.linesep; on Windows, for example, the end-of-line marker is ‘rn’).

If you don’t like your platform’s default, you can override it using the ‘linesep=’ keyword argument. If you specifically want write_text() to preserve the newlines as-is, use ‘linesep=None’.

This applies to Unicode text the same as to 8-bit text, except there are three additional standard Unicode end-of-line sequences: u’x85’, u’rx85’, and u’u2028’.

(This is slightly different from when you open a file for writing with fopen(filename, “w”) in C or open(filename, ‘w’) in Python.)

— Unicode

If ‘text’ isn’t Unicode, then apart from newline handling, the bytes are written verbatim to the file. The ‘encoding’ and ‘errors’ arguments are not used and must be omitted.

If ‘text’ is Unicode, it is first converted to bytes using the specified ‘encoding’ (or the default encoding if ‘encoding’ isn’t specified). The ‘errors’ argument applies only to this conversion.

paver.runtime.cmdopts(options, share_with=None)

Sets the command line options that can be set for this task. This uses the same format as the distutils command line option parser. It’s a list of tuples, each with three elements: long option name, short option, description.

If the long option name ends with ‘=’, that means that the option takes a value. Otherwise the option is just boolean. All of the options will be stored in the options dict with the name of the task. Each value that gets stored in that dict will be stored with a key that is based on the long option name (the only difference is that - is replaced by _).

paver.runtime.consume_args(func)

Any command line arguments that appear after this task on the command line will be placed in options.args.

paver.setuputils module

Integrates distutils/setuptools with Paver.

class paver.setuputils.DistutilsTask(distribution, command_name, command_class)

Bases: paver.tasks.Task

description
class paver.setuputils.DistutilsTaskFinder

Bases: object

get_task(taskname)
get_tasks()
paver.setuputils.find_package_data(where='.', package='', exclude=('*.py', '*.pyc', '*~', '.*', '*.bak', '*.swp*'), exclude_directories=('.*', 'CVS', '_darcs', './build', './dist', 'EGG-INFO', '*.egg-info'), only_in_packages=True, show_ignored=False)

Return a dictionary suitable for use in package_data in a distutils setup.py file.

The dictionary looks like:

{'package': [files]}

Where files is a list of all the files in that package that don’t match anything in exclude.

If only_in_packages is true, then top-level directories that are not packages won’t be included (but directories under packages will).

Directories matching any pattern in exclude_directories will be ignored; by default directories with leading ., CVS, and _darcs will be ignored.

If show_ignored is true, then all the files that aren’t included in package data are shown on stderr (for debugging purposes).

Note patterns use wildcards, or can be exact paths (including leading ./), and all searching is case-insensitive.

This function is by Ian Bicking.

paver.setuputils.install_distutils_tasks()

Makes distutils and setuptools commands available as Paver tasks.

paver.setuputils.setup(**kw)

Updates options.setup with the keyword arguments provided, and installs the distutils tasks for this pavement. You can use paver.setuputils.setup as a direct replacement for the distutils.core.setup or setuptools.setup in a traditional setup.py.

paver.shell module

paver.shell.sh(command, capture=False, ignore_error=False, cwd=None, env=None)

Runs an external command. If capture is True, the output of the command will be captured and returned as a string. If the command has a non-zero return code raise a BuildFailure. You can pass ignore_error=True to allow non-zero return codes to be allowed to pass silently, silently into the night. If you pass cwd=’some/path’ paver will chdir to ‘some/path’ before exectuting the command.

If the dry_run option is True, the command will not actually be run.

env is a dictionary of environment variables. Refer to subprocess.Popen’s documentation for further information on this.

paver.ssh module

Functions for accessing remote hosts.

At present, these are implemented by calling ssh’s command line programs.

paver.ssh.scp(source, dest)

Copy the source file to the destination.

paver.svn module

Convenience functions for working with svn.

This module does not include any tasks, only functions.

At this point, these functions do not use any kind of library. They require the svn binary on the path.

paver.svn.checkout(url, dest, revision='')

Checks out the specified URL to the given destination.

paver.svn.checkup(url, dest, revision='')

Does a checkout or update, depending on whether the destination exists and is up to date (if a revision is passed in). Returns true if a checkout or update was performed. False otherwise.

paver.svn.export(url, dest, revision='')

Exports the specified URL to the given destination.

paver.svn.info(path='')

Retrieves the svn info for the path and returns a dictionary of the values. Names are normalized to lower case with spaces converted to underscores.

paver.svn.update(path='', revision='')

Run an svn update on the given path.

paver.tasks module

exception paver.tasks.BuildFailure

Bases: exceptions.Exception

Represents a problem with some part of the build’s execution.

class paver.tasks.Environment(pavement=None)

Bases: object

call_task(task_name, args=None, options=None)
debug(message, *args)
dry_run
error(message, *args)
file
get_task(taskname)
get_tasks()
info(message, *args)
interactive = False
pavement_file
quiet = False
verbose = False
exception paver.tasks.PavementError

Bases: exceptions.Exception

Exception that represents a problem in the pavement.py file rather than the process of running a build.

class paver.tasks.Task(func)

Bases: object

called = False
consume_args = 0
description
display_help(parser=None)
needs_closure
no_auto = False
parse_args(args)
parser
paver.tasks.call_pavement(new_pavement, args)
paver.tasks.cmdopts(options, share_with=None)

Sets the command line options that can be set for this task. This uses the same format as the distutils command line option parser. It’s a list of tuples, each with three elements: long option name, short option, description.

If the long option name ends with ‘=’, that means that the option takes a value. Otherwise the option is just boolean. All of the options will be stored in the options dict with the name of the task. Each value that gets stored in that dict will be stored with a key that is based on the long option name (the only difference is that - is replaced by _).

paver.tasks.consume_args(func)

Any command line arguments that appear after this task on the command line will be placed in options.args.

paver.tasks.consume_nargs(nb_args=None)

All specified command line arguments that appear after this task on the command line will be placed in options.args. By default, if nb_args is not specified, all arguments will be consumed.

Parameters:nb_args (int) – number of arguments the decorated function consumes
paver.tasks.help(args, help_function)

This help display.

paver.tasks.main(args=None)
paver.tasks.might_call(*args)
paver.tasks.needs(*args)

Specifies tasks upon which this task depends.

req can be a string or a list of strings with the names of the tasks. You can call this decorator multiple times and the various requirements are added on. You can also call with the requirements as a list of arguments.

The requirements are called in the order presented in the list.

paver.tasks.no_auto(func)

Specify that this task does not depend on the auto task, and don’t run the auto task just for this one.

paver.tasks.no_help(func)

Do not show this task in paver help.

paver.tasks.task(func)

Specifies that this function is a task.

Note that this decorator does not actually replace the function object. It just keeps track of the task and sets an is_task flag on the function object.

paver.version module

paver.virtual module

Tasks for managing virtualenv environments.

paver.virtual.bootstrap()

Creates a virtualenv bootstrap script. The script will create a bootstrap script that populates a virtualenv in the current directory. The environment will have paver, the packages of your choosing and will run the paver command of your choice.

This task looks in the virtualenv options for:

script_name
name of the generated script
packages_to_install
packages to install with pip/easy_install. The version of paver that you are using is included automatically. This should be a list of strings.
paver_command_line
run this paver command line after installation (just the command line arguments, not the paver command itself).
dest_dir
the destination directory for the virtual environment (defaults to ‘.’)
no_site_packages
don’t give access to the global site-packages dir to the virtual environment (default; deprecated)
system_site_packages
give access to the global site-packages dir to the virtual environment
unzip_setuptools
unzip Setuptools when installing it (defaults to False)
distribute
use Distribute instead of Setuptools. Set environment variable VIRTUALENV_DISTRIBUTE to make it the default.
index_url
base URL of Python Package Index
trusted_host
specify whether the given index_url is a trusted host to avoid deprecated warnings
no_index
ignore package index (only looking at find_links URL(s) instead)
find_links
additional URL(s) to search for packages. This should be a list of strings.
prefer_easy_install
prefer easy_install to pip for package installation if both are installed (defaults to False)
paver.virtual.virtualenv(dir)

Run decorated task in specified virtual environment.

Module contents