Pavement runtime helpers

Helper functions and data structures used by pavements.

exception paver.runtime.BuildFailure
Represents a problem with some part of the build’s execution.
class paver.runtime.Bunch
A dictionary that provides attribute-style access.
class paver.runtime.Namespace(d=None, **kw)

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.

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
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, a BuildFailure 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.runtime.PavementError
Exception that represents a problem in the pavement.py file rather than the process of running a build.
class paver.runtime.Task(func)

Keeps track of the metadata for a function that is used as a pavement task. Also provides the bridge to distutils.

distutils_command
Get the distutils Command class for this task.
valid(options)
Determine if this task is allowable given the current build environment.
paver.runtime.call_task(task_name, options=None)

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.cmdopts(options)

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.runtime.debug(message, *args)
Displays a message to the user, but only if the verbose flag is set.
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.needs(req)

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.

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

paver.runtime.require_keys(keys)
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)

Runs an external command. If capture is True, the output of the command will be captured and returned as a string.

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

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.