util Package¶

`util` Package¶

Utility functions and classes for Dovetail.

`exception` Module¶

Dovetail exceptions

exception dovetail.util.exception.CircularTaskDependency(task, stack, *kw, **kwargs)¶

Bases: dovetail.util.exception.DovetailException

An exception raised when a Task has a circular reference on another Task.

This is a condition that is detected at run-time.

The Exception contains two members that record the dependency:

self.task: The Task on which the circular dependency was detected, and

self.stack: The call-stack at the point of the detection. The call-stack is a list of Tasks

exception dovetail.util.exception.CommandLineException(return_code, message)¶

Bases: dovetail.util.exception.DovetailException

The superclass of all exceptions that should be handled by the command-line routine and for which no stack trace should be printed

additional_help()¶: Returns an additional help string to help the user localize the problem

exception dovetail.util.exception.DovetailException¶

Bases: exceptions.Exception

The superclass of all Dovetail exceptions

exception dovetail.util.exception.FailIf¶

Bases: dovetail.util.exception.DovetailException

An exception raised by @fail_if when the predicate is False

exception dovetail.util.exception.InvalidBuildFile(message)¶

Bases: dovetail.util.exception.CommandLineException

An exception raised when a build file is specified, but cannot be found, is not readable or has the wrong extension

exception dovetail.util.exception.InvalidEnvironment(message)¶

Bases: dovetail.util.exception.CommandLineException

An exception stating that the specified environment is badly configured, inaccessible or otherwise not valid

exception dovetail.util.exception.InvalidTask(message)¶

Bases: dovetail.util.exception.CommandLineException

An exception raised when a Task file is specified on the command line, but cannot be found

exception dovetail.util.exception.MissingRequirement¶

Bases: dovetail.util.exception.DovetailException

An exception thrown when easy_install cannot resolve or install a requirement.

exception dovetail.util.exception.NoSuchDirectory¶

Bases: dovetail.util.exception.DovetailException

An exception raised when a directive requires use of a directory which does not exist or is not readable

exception dovetail.util.exception.NoSuchModule¶

Bases: dovetail.util.exception.DovetailException

An exception raised when either a module cannot be found (has not been loaded by Python, or when it is not a BuildModule

exception dovetail.util.exception.NoSuchTask¶

Bases: dovetail.util.exception.DovetailException

An exception raised when a Task is referenced and it has not be loaded

exception dovetail.util.exception.NonZeroReturnCode¶

Bases: dovetail.util.exception.DovetailException

An exception raised by @check_result when the task returns with a non-zero value

exception dovetail.util.exception.Skipped¶

Bases: dovetail.util.exception.DovetailException

An exception raised by the @fail_if_skipped directive if the Task was skipped:

exception dovetail.util.exception.Terminate(return_code, message)¶

Bases: dovetail.util.exception.CommandLineException

An exception raised for a generic problem in parsing the command line arguments or if Dovetail crashes during a build.

Note

This is not raised if a build task fails or throws an exception

additional_help()¶

exception dovetail.util.exception.UnknownReport(return_code, message)¶

Bases: dovetail.util.exception.CommandLineException

An exception raised if requested to generate a report that is not known to it

dovetail.util.exception.pp_exception(exception)¶: Pretty-print an exception

dovetail.util.exception.stack_trace()¶: Obtains then prints a formatted stack-trace to std_err

`logging` Module¶

Logging and stdout formatting

dovetail.util.logging.LEVEL¶

Enumeration of different logging levels:

DEBUG
INFO
MAJOR
WARN
ERROR

alias of Enum

class dovetail.util.logging.Logger¶

Bases: object

Co-ordinates output from the execution of Dovetail.

The global variable LEVEL contains an enumeration of the following log levels:

LEVEL.DEBUG - Debugging information. Very verbose

LEVEL.INTO - Default level

LEVEL.MAJOR - important messages and sys.stdout

LEVEL.WARN

LEVEL.ERROR - errors and sys.stderr

The overall reporting level is changed by calling Message.setLevel()

static debug(message)¶: Logs a method at DEBUG level

static ends_with_newline(message)¶: Return True if the message ends with a new line

static error(message)¶: Logs a method at ERROR level

static flush()¶: Flushes all output to the logging channels

static log(message, level=1)¶: Logs a message to the currently executing frame

static major(message)¶: Logs a method at MAJOR level

static set_frame(frame)¶: Sets the Logger frame which is used to calculate the indent when nesting the logging output

static set_level(level)¶

Sets the overall level of log output.

This setting does not adjust what is captured, only what is reported

static set_nested(nested)¶

Switch nesting of the log file on or off.

Can only be called when Tasks are not executing

static show(level)¶: Returns True if level >= logging level

static warn(message)¶: Logs a method at ERROR level

class dovetail.util.logging.Message(message, level=1)¶

Bases: object

A log message capturing a piece of information about the execution of Dovetail.

Attributes:

Attribute	Type	Description
message	string	The line captured from the logging system
level	Enum from `LEVEL`	The log level
when	`datetime.datetime`	When the message was received

Note

The overall reporting level is changed by calling Logging.setLevel().

shown()¶: Returns True if this message should be shown (its level >= logging level)

class dovetail.util.logging.StdErr(message)¶

Bases: object

A log message which was captured from stderr

shown()¶: Returns True if the error should be shown, which is likely always True

`test_utilities` Module¶

py.test test script for utilities.py

class dovetail.util.test_utilities.TestEnum¶

enumeration¶: alias of Enum

test_as_str()¶

test_as_str_miss()¶

test_basics()¶

test_lookup()¶

test_lookup_miss()¶

test_names()¶

`trim` Module¶

Sorts out the docstring indentation as per PEP 257.

dovetail.util.trim.trim(docstring)¶: Reformats a docstring, replacing tabs with spaces and repaginating

`utilities` Module¶

Utility functions.

dovetail.util.utilities.args_as_str(*kw, **kwargs)¶: Pretty prints a list of arguments of a function

dovetail.util.utilities.call(arguments, shell=False, stdout=None, stdout_mode='w', stdout_buffer=-1, stderr=None, stderr_mode='w', stderr_buffer=-1)¶

A convenience function that wraps subprocess.call() but allows the developer to specify stdout and stderr not as streams but files.

A typical use would be:

>>> call('pylint src'.split(' '), stdout='pylint.out')

This would run pylint on the src subdirectory, capturing all stdout in the file pylint.out. The opening and closing are automatically handled.

The file’s mode and buffer are optionally specified using the std[out|err]_mode and std[out|err]_buffer arguments. The values and semantics are exactly as in the open(file, mode, buffering) function. The defaults are mode=”w” and buffering=None.

The return value is the value returned by the wrapped subprocess.call() function.

dovetail.util.utilities.enum(**enums)¶

Creates an instance of an Enum class, instantiated with values.

Usage:

>>> Numbers = enum(ONE=1, TWO=2, THREE='three')
>>> Numbers.ONE
1
>>> Numbers.TWO
2
>>> Numbers.THREE
'three'

Enums are created with the following methods:

as_str(). Returns the string name of the instance:
>>> Numbers.as_str(Numbers.ONE)
'ONE'
contains(value): Returns True if the value is a member of the enumeration:
>>> Numbers.contains(Numbers.ONE)
True
>>> Numbers.contains('ONE')
False
>>> Numbers.contains(1)
True
lookup(name): Looks up an instance by the name of the key:
>>> Numbers.lookup('ONE')
1
lookup(name) and as_str() are reflexive. For any member m of an enumeration e, the following must be true:
>>> e.lookup(e.as_str(e.m)) is e.m
True
names(): Returns a list of names in the enumeration:
>>>Numbers.names()
['THREE', 'TWO', 'ONE']

dovetail.util.utilities.get_virtual_environment()¶: Gets the path of this virtual environment, if dovetail is running as a slave, otherwise None

dovetail.util.utilities.set_virtual_environment(virtualenv)¶

Sets the path to the slave virtualenv environment.

See get_virtual_environment()

dovetail.util.utilities.stamp_environment()¶

Writes a lot of system information into the os.environ.

Environment Variable Name	How obtained (eg Python API)	Eg Win	Eg Mac
About the machine hardware
`DOVETAIL_MACHINE`	`platform.machine()`	x86	x86_64
`DOVETAIL_PROCESSOR`	`platform.processor()`	...	i386
About the OS
`DOVETAIL_OS_NAME`	`os.name`	nt	posix
`DOVETAIL_SYSTEM`	`platform.system()`	Windows	Darwin
`DOVETAIL_RELEASE`	`platform.release()`	XP	11.3.0
Information about Python itself
`DOVETAIL_PYTHON_EXECUTABLE`	`sys.executable`	Path to Python executable
`DOVETAIL_PYTHON_IMPLEMENTATION`	`platform.python_implementation()`	CPython, IronPython, PyPy, Jython
`DOVETAIL_PYTHON_MAJOR_VERSION`	`platform.python_version_tuple()`	2	2
`DOVETAIL_PYTHON_MINOR_VERSION`	`platform.python_version_tuple()`	2.7	2.7
`DOVETAIL_PYTHON_VERSION`	`platform.python_version_tuple()`	2.7.1	2.7.1
`DOVETAIL_BUILD_PLATFORM`	`pkg_resourses.get_build_platform()`	win32	macosx-10.7-intel
About the environment
`DOVETAIL_VERSION`	`dovetail.constants.VERSION`	1.0	1.0
`DOVETAIL_NODE`	`platform.node()`	Machine’s network name
`DOVETAIL_USER`	`getpass.getuser()`	Username of build user
`DOVETAIL_VIRTUALENV_SLAVE`	Set if running in a slave	Path to virtualenv

dovetail.util.utilities.tree(root, get_children, node_text=<type 'str'>, display_root=True, indent=1, separator=1, node_style=False, margin=' ')¶

Produce a hierarchical text tree.

The function takes three arguments that must ‘agree’:

root: A root of a tree. Root and all its descendants must be of duck type <node>.

node_text(): A function that ‘renders’ objects of type <node>

get_children() A function that returns the children of any node. The children must be returned in an iterable, such as a list.

Parameters:	root (Object) – The root node of the tree node_text (function(node) -> string) – Function to get display text for a node in the tree. Can return multiple lines. get_children (function(node) -> iterable<node>) – A function which returns an iterable of the children of a node. These children will be looped over as the next level of nodes. display_root (boolean) – If True, the root’s text is displayed otherwise only the children are displayed indent (int) – Number of characters than each extra level indents by. Defaults to 1 for a horizontally-tight tree node_style (boolean) – When True, the nodes are different from leaves, and the vertical node expansions are drawn under the node (influenced by the indent argument). When False, the nodes and leaves are drawn the same, vertical expansions are drawn from the main tree separator (int) – Number of lines between each node in the tree. Defaults to 1 to provide some spacing between nodes. Use 0 for a vertically-tighter tree margin (string) – The left margin of the report which is repeated each on each line. Defaults to a two spaces.
Returns:	A text representation of the tree root
Return type:	string

`which` Module¶

A multi-platform implementation of the Unix ‘which’ command in Python.

dovetail.util.which.which(program)¶

A Python implementation of the Unix ‘which’ command, which tests whether the argument is a program either directly accessible or is on the system path.

Parameters:	program (string) – The name of a file that should be on the path
Returns:	The full path of the first executable found, or None if the executable is not on the path
Return type:	string

util Package¶

`util` Package¶

`exception` Module¶

`logging` Module¶

`test_utilities` Module¶

`trim` Module¶

`utilities` Module¶

`which` Module¶

Table Of Contents

Previous topic

Next topic

Navigation

util Package¶

util Package¶

exception Module¶

logging Module¶

test_utilities Module¶

trim Module¶

utilities Module¶

which Module¶

Table Of Contents

Previous topic

Next topic

Quick search

`util` Package¶

`exception` Module¶

`logging` Module¶

`test_utilities` Module¶

`trim` Module¶

`utilities` Module¶

`which` Module¶