Classes
class	SubprocessError
	Exception thrown when command execution failed. More...
Functions
def	execute
	Execute command as subprocess.
def	exedir
	Get directory of executable file.
def	exename
	Get name of executable file.
def	exepath
	Get absolute path of executable file.
def	istarget
	Determine whether a given build target is known.
def	print_contact
	Print contact information.
def	print_version
	Print version information including copyright and license notices.
def	qsplit
	Split quoted string of arguments.
def	targetuid
	Get UID of build target.
def	tostring
	Convert array of arguments to quoted string.
Variables
list	__all__ = []
tuple	_MODULE_DIR = os.path.dirname(os.path.realpath(__file__))
string	CONTACT = "SBIA Group <sbia-software at uphs.upenn.edu>"
	Default contact to use for help output of executables.
string	COPYRIGHT = "2011, 2012, 2013 University of Pennsylvania"
	Default copyright of executables.
string	LICENSE = "See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file."
	Default license of executables.

Function Documentation

def basis::utilities::execute	(	args,
		quiet = `False`,
		stdout = `False`,
		allow_fail = `False`,
		verbose = `0`,
		simulate = `False`,
		prefix = `None`,
		targets = `None`,
		base = `'.'`
	)

Execute command as subprocess.

Parameters:

[in]	args	Command with arguments given either as quoted string or array of command name and arguments. In the latter case, the array elements are converted to strings using the built-in str() function. Hence, any type which can be converted to a string is permitted. The first argument must be the name or path of the executable of the command.
[in]	quiet	Turns off output of `stdout` of child process to stdout of parent process.
[in]	stdout	Whether to return the command output.
[in]	allow_fail	If true, does not raise an exception if return value is non-zero. Otherwise, a `SubprocessError` is raised by this function.
[in]	verbose	Verbosity of output messages. Does not affect verbosity of executed command.
[in]	simulate	Whether to simulate command execution only.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.
[in]	base	Base directory for relative paths in `targets`.

Returns:: The exit code of the subprocess if stdout is false (the default). Otherwise, if stdout is true, a tuple consisting of exit code command output is returned. Note that if allow_fail is false, the returned exit code will always be 0.

Exceptions:

SubprocessError If command execution failed. This exception is not raised if the command executed with non-zero exit code but allow_fail set to True.

Definition at line 291 of file utilities.py.

def basis::utilities::exedir	(	name = `None`,
		prefix = `None`,
		targets = `None`,
		base = `'.'`
	)

Get directory of executable file.

Parameters:

[in]	name	Name of command or `None`.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.
[in]	base	Base directory for relative paths in `targets`.

Returns:: Absolute path of directory containing executable or None if not found. If name is None, the directory of this executable is returned.

Definition at line 209 of file utilities.py.

def basis::utilities::exename	(	name = `None`,
		prefix = `None`,
		targets = `None`,
		base = `'.'`
	)

Get name of executable file.

Parameters:

[in]	name	Name of command or `None`.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.
[in]	base	Base directory for relative paths in `targets`.

Returns:: Name of executable file or None if not found. If name is None, the name of this executable is returned.

Definition at line 191 of file utilities.py.

def basis::utilities::exepath	(	name = `None`,
		prefix = `None`,
		targets = `None`,
		base = `'.'`
	)

Get absolute path of executable file.

This function determines the absolute file path of an executable. If no arguments are given, the absolute path of this executable is returned. If the command names a known executable build target, the absolute path to the corresonding built (and installed) executable file is returned. Otherwise, the named command is searched in the system PATH and its absolute path returned if found. If the executable is not found, None is returned.

Parameters:

[in]	name	Name of command or `None`.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.
[in]	base	Base directory for relative paths in `targets`.

Returns:: Absolute path of executable or None if not found. If name is None, the path of this executable is returned.

Definition at line 159 of file utilities.py.

def basis::utilities::istarget	(	name,
		prefix = `None`,
		targets = `None`
	)

Determine whether a given build target is known.

Parameters:

[in]	name	Name of build target.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.

Returns:: Whether the named target is a known executable target.

Definition at line 135 of file utilities.py.

def basis::utilities::print_contact ( contact = CONTACT )

Print contact information.

Parameters:

[in] contact Name of contact.

Definition at line 57 of file utilities.py.

def basis::utilities::print_version	(	name,
		version = `None`,
		project = `None`,
		copyright = `COPYRIGHT`,
		license = `LICENSE`
	)

Print version information including copyright and license notices.

Parameters:

[in]	name	Name of executable. Should not be set programmatically to the first argument of the `__main__` module, but a string literal instead.
[in]	version	Version of executable, e.g., release of project this executable belongs to.
[in]	project	Name of project this executable belongs to. If `None`, or an empty string, no project information is printed.
[in]	copyright	The copyright notice, excluding the common prefix "Copyright (c) " and suffix ". All rights reserved.". If `None`, or an empty string, no copyright notice is printed.
[in]	license	Information regarding licensing. If `None` or an empty string, no license information is printed.

Definition at line 77 of file utilities.py.

def basis::utilities::qsplit ( args )

Split quoted string of arguments.

Parameters:

[in] args Quoted string of arguments.

Returns:: Array of arguments.

See also:: to_quoted_string()

Definition at line 257 of file utilities.py.

def basis::utilities::targetuid	(	name,
		prefix = `None`,
		targets = `None`
	)

Get UID of build target.

The UID of a build target is its name prepended by a namespace identifier which should be unique for each project.

Parameters:

[in]	name	Name of build target.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.

Returns:: UID of named build target.

Definition at line 109 of file utilities.py.

def basis::utilities::tostring ( args )

Convert array of arguments to quoted string.

Parameters:

[in] args Array of arguments.

Returns:: Double quoted string, i.e., string where arguments are separated by a space character and surrounded by double quotes if necessary. Double quotes within an argument are escaped with a backslash.

See also:: split_quoted_string()

Definition at line 238 of file utilities.py.

Variable Documentation

list basis::utilities::__all__ = []

Definition at line 23 of file utilities.py.

tuple basis::utilities::_MODULE_DIR = os.path.dirname(os.path.realpath(__file__))

Definition at line 47 of file utilities.py.

Classes

Functions

Variables

Function Documentation

Variable Documentation