paver package — Paver 1.3.4 documentation

# paver package

## Subpackages

- paver.deps package
  - Submodules
  - paver.deps.path2 module
  - paver.deps.path3 module
  - Module contents
- paver.tests package
  - Submodules
  - paver.tests.other_pavement module
  - paver.tests.test_doctools module
  - paver.tests.test_git module
  - paver.tests.test_hg module
  - paver.tests.test_options module
  - paver.tests.test_path module
  - paver.tests.test_setuputils module
  - paver.tests.test_shell module
  - paver.tests.test_svn module
  - paver.tests.test_tasks module
  - paver.tests.utils module
  - Module contents

## 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.misctasks.` `paverdocs`()

  Open your web browser and display Paver’s documentation.

## 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: `Exception`

## paver.path module

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

class `paver.path.` `path`

  Bases: `paver.deps.path3.path`

  `chdir`()
  `chmod`(mode)
  `chown`(uid, gid)
  `copy`(src, dst, *, follow_symlinks=True)

    Copy data and mode bits (“cp src dst”). Return the file’s destination.

    The destination may be a directory.

    If follow_symlinks is false, symlinks won’t be followed. This resembles GNU’s “cp -P src dst”.

    If source and destination are the same file, a SameFileError will be raised.

  `copy2`(src, dst, *, follow_symlinks=True)

    Copy data and all stat info (“cp -p src dst”). Return the file’s destination.”

    The destination may be a directory.

    If follow_symlinks is false, symlinks won’t be followed. This resembles GNU’s “cp -P src dst”.

  `copyfile`(src, dst, *, follow_symlinks=True)

    Copy data from src to dst.

    If follow_symlinks is not set and src is a symbolic link, a new symlink will be created instead of copying the file it points to.

  `copymode`(src, dst, *, follow_symlinks=True)

    Copy mode bits from src to dst.

    If follow_symlinks is not set, symlinks aren’t followed if and only if both src and dst are symlinks. If lchmod isn’t available (e.g. Linux) this method does nothing.

  `copystat`(src, dst, *, follow_symlinks=True)

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

    If the optional flag follow_symlinks is not set, symlinks aren’t followed if and only if both src and dst are symlinks.

  `copytree`(src, dst, symlinks=False, ignore=None, copy_function=<function copy2>, ignore_dangling_symlinks=False)

    Recursively copy a directory tree.

    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. If the file pointed by the symlink doesn’t exist, an exception will be added in the list of errors raised in an Error exception at the end of the copy process.

    You can set the optional ignore_dangling_symlinks flag to true if you want to silence this exception. Notice that this has no effect on platforms that don’t support os.symlink.

    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.

    The optional copy_function argument is a callable that will be used to copy each file. It will be called with the source path and the destination path as arguments. By default, copy2() is used, but any function that supports the same signature (like copy()) can be used.

  `link`(newpath)

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

  `makedirs`(mode=511)
  `makedirs_p`(mode=511)
  `mkdir`(mode=511)
  `mkdir_p`(mode=511)
  `move`(src, dst)

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

    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. Symlinks are recreated under the new name if os.rename() fails because of cross filesystem renames.

    A lot more could be done here… A look at a mv.c shows a lot of the issues this implementation glosses over.

  `remove`()
  `remove_p`()
  `removedirs`()
  `removedirs_p`()
  `rename`(new)
  `renames`(new)
  `rmdir`()
  `rmdir_p`()
  `rmtree`(*args, **kw)
  `rmtree_p`()
  `symlink`(newlink)

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

  `touch`()

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

  `unlink`()
  `unlink_p`()
  `utime`(times)

    Set the access and modified times of this file.

  `write_bytes`(bytes, append=False)

    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`(lines, encoding=None, errors='strict', linesep='\n', append=False)

    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`(text, encoding=None, errors='strict', linesep='\n', append=False)

    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`(dir)

  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: `Exception`

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

exception `paver.runtime.` `PavementError`

  Bases: `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.path3.path`

  `chdir`()
  `chmod`(mode)
  `chown`(uid, gid)
  `copy`(src, dst, *, follow_symlinks=True)

    Copy data and mode bits (“cp src dst”). Return the file’s destination.

    The destination may be a directory.

    If follow_symlinks is false, symlinks won’t be followed. This resembles GNU’s “cp -P src dst”.

    If source and destination are the same file, a SameFileError will be raised.

  `copy2`(src, dst, *, follow_symlinks=True)

    Copy data and all stat info (“cp -p src dst”). Return the file’s destination.”

    The destination may be a directory.

    If follow_symlinks is false, symlinks won’t be followed. This resembles GNU’s “cp -P src dst”.

  `copyfile`(src, dst, *, follow_symlinks=True)

    Copy data from src to dst.

    If follow_symlinks is not set and src is a symbolic link, a new symlink will be created instead of copying the file it points to.

  `copymode`(src, dst, *, follow_symlinks=True)

    Copy mode bits from src to dst.

    If follow_symlinks is not set, symlinks aren’t followed if and only if both src and dst are symlinks. If lchmod isn’t available (e.g. Linux) this method does nothing.

  `copystat`(src, dst, *, follow_symlinks=True)

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

    If the optional flag follow_symlinks is not set, symlinks aren’t followed if and only if both src and dst are symlinks.

  `copytree`(src, dst, symlinks=False, ignore=None, copy_function=<function copy2>, ignore_dangling_symlinks=False)

    Recursively copy a directory tree.

    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. If the file pointed by the symlink doesn’t exist, an exception will be added in the list of errors raised in an Error exception at the end of the copy process.

    You can set the optional ignore_dangling_symlinks flag to true if you want to silence this exception. Notice that this has no effect on platforms that don’t support os.symlink.

    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.

    The optional copy_function argument is a callable that will be used to copy each file. It will be called with the source path and the destination path as arguments. By default, copy2() is used, but any function that supports the same signature (like copy()) can be used.

  `link`(newpath)

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

  `makedirs`(mode=511)
  `makedirs_p`(mode=511)
  `mkdir`(mode=511)
  `mkdir_p`(mode=511)
  `move`(src, dst)

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

    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. Symlinks are recreated under the new name if os.rename() fails because of cross filesystem renames.

    A lot more could be done here… A look at a mv.c shows a lot of the issues this implementation glosses over.

  `remove`()
  `remove_p`()
  `removedirs`()
  `removedirs_p`()
  `rename`(new)
  `renames`(new)
  `rmdir`()
  `rmdir_p`()
  `rmtree`(*args, **kw)
  `rmtree_p`()
  `symlink`(newlink)

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

  `touch`()

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

  `unlink`()
  `unlink_p`()
  `utime`(times)

    Set the access and modified times of this file.

  `write_bytes`(bytes, append=False)

    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`(lines, encoding=None, errors='strict', linesep='\n', append=False)

    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`(text, encoding=None, errors='strict', linesep='\n', append=False)

    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: `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: `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