Auxiliary implementations for use in Python scripts. More...

Collaboration diagram for Python Utilities:

Files
file	basis.py
	BASIS utilities of BASIS package.
file	utilities.py
	Main module of project-independent BASIS utilities.
Functions
def	basis::execute
	Execute command as subprocess.
def	basis::exedir
	Get directory of executable file.
def	basis::exename
	Get name of executable file.
def	basis::exepath
	Get absolute path of executable file.
def	basis::istarget
	Determine whether a given build target is known.
def	basis::print_contact
	Print contact information.
def	basis::print_version
	Print version information including copyright and license notices.
def	basis::targetuid
	Get UID of build target.
Variables
dictionary	basis::_EXECUTABLE_TARGETS
string	basis::_TARGET_UID_PREFIX = 'basis'
tuple	basis::_TARGETS_BASE = os.path.dirname(os.path.realpath(__file__))
const char *	basis::CONTACT = "SBIA Group <sbia-software at uphs.upenn.edu>"
	Default contact to use for help output of executables.
const char *	basis::COPYRIGHT = "2011, 2012, 2013 University of Pennsylvania"
	Default copyright of executables.
const char *	basis::LICENSE = "See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file."
	Default license of executables.
const char *	basis::PROJECT = "BASIS"
	The project name.
cmake	PROJECT_NAMESPACE_JYTHON
	CMake variable of Jython package name of project.
cmake	PROJECT_NAMESPACE_PYTHON
	CMake variable of Python package name of project.
	basis::qsplit = utilities.qsplit
	Split quoted string of arguments.
const char *	basis::RELEASE = "r3148"
	Complete version information as output by --version option.
	basis::SubprocessError = utilities.SubprocessError
	Exception thrown when command execution failed.
	basis::tostring = utilities.tostring
	Convert array of arguments to quoted string.
const char *	basis::VERSION = "0.0.0"
	The version string given as "<major>.<minor>.<patch>".

Detailed Description

Auxiliary implementations for use in Python scripts.

Function Documentation

def basis::execute	(	args,
		quiet = `False`,
		stdout = `False`,
		allow_fail = `False`,
		verbose = `0`,
		simulate = `False`,
		prefix = `_TARGET_UID_PREFIX`,
		targets = `_EXECUTABLE_TARGETS`,
		base = `_TARGETS_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 build targets belonging to this project.
[in]	targets	Dictionary which maps build target names to executable file paths. The code to initialize this dictionary is generated by BASIS.
[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 297 of file basis.py.

def basis::exedir	(	name = `None`,
		prefix = `_TARGET_UID_PREFIX`,
		targets = `_EXECUTABLE_TARGETS`,
		base = `_TARGETS_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 229 of file basis.py.

def basis::exename	(	name = `None`,
		prefix = `_TARGET_UID_PREFIX`,
		targets = `_EXECUTABLE_TARGETS`,
		base = `_TARGETS_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 216 of file basis.py.

def basis::exepath	(	name = `None`,
		prefix = `_TARGET_UID_PREFIX`,
		targets = `_EXECUTABLE_TARGETS`,
		base = `_TARGETS_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 203 of file basis.py.

def basis::istarget	(	name,
		prefix = `_TARGET_UID_PREFIX`,
		targets = `_EXECUTABLE_TARGETS`
	)

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 182 of file basis.py.

def basis::print_contact ( contact = CONTACT )

Print contact information.

Parameters:

[in] contact Name of contact.

Definition at line 133 of file basis.py.

def basis::print_version	(	name,
		version = `RELEASE`,
		project = `PROJECT`,
		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 153 of file basis.py.

def basis::targetuid	(	name,
		prefix = `_TARGET_UID_PREFIX`,
		targets = `_EXECUTABLE_TARGETS`
	)

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 171 of file basis.py.

Variable Documentation

dictionary basis::_EXECUTABLE_TARGETS

Initial value:

00001 {
00002     'basis.basisproject':      '../../../bin/basisproject',
00003     'basis.doxyfilter':        '../../doxyfilter',
00004     'basis.doxyfilter-perl':   '../../doxyfilter-perl',
00005     'basis.testdriver':        '../../testdriver',
00006     'basis.basistest-svn':     '../../basistest-svn',
00007     'basis.basistest-slave':   '../../basistest-slave',
00008     'basis.basistest-master':  '../../basistest-master',
00009     'basis.basistest-cron':    '../../basistest-cron',
00010     'basis.basistest':         '../../../bin/basistest',
00011     'basis.dummy_command':     '../../../bin/dummy_command',
00012     'basis.test_matlabtools':  '',
00013     'basis.test_basisproject': '',
00014     'basis.test_os':           '../../../bin/test_os',
00015     'basis.test_path':         '../../../bin/test_path',
00016     'basis.test_subprocess':   '../../../bin/test_subprocess',
00017     'basis.test_core':         '',
00018     'basis.test_shutilities':  '',
00019     'basis.test_shtap':        '',
00020     'basis.parseargs':         '../../../bin/parseargs',
00021     'basis.test_utilities':    '',
00022 }

Definition at line 100 of file basis.py.

string basis::_TARGET_UID_PREFIX = 'basis'

Definition at line 98 of file basis.py.

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

Definition at line 123 of file basis.py.

string basis::CONTACT = "SBIA Group <sbia-software at uphs.upenn.edu>"

Default contact to use for help output of executables.

Definition at line 43 of file basis.cxx.

string basis::COPYRIGHT = "2011, 2012, 2013 University of Pennsylvania"

Default copyright of executables.

Definition at line 41 of file basis.cxx.

string basis::LICENSE = "See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file."

Default license of executables.

Definition at line 42 of file basis.cxx.

string basis::PROJECT = "BASIS"

The project name.

Project name.

Definition at line 33 of file basis.cxx.

cmake PROJECT_NAMESPACE_JYTHON

CMake variable of Jython package name of project.

The Jython package name of a BASIS project is made up of the vendor name and the name of the package itself. Moreover, if the project is a module of another project, the name of the module may optionally be used as part of the namespace as well. Names of packages and sub-packages in Jython are usually in lowercase only.

Definition at line 105 of file ProjectSettings.cmake.

cmake PROJECT_NAMESPACE_PYTHON

CMake variable of Python package name of project.

The Python package name of a BASIS project is made up of the vendor name and the name of the package itself. Moreover, if the project is a module of another project, the name of the module may optionally be used as part of the namespace as well. Names of packages and sub-packages in Python are usually in lowercase only.

Definition at line 95 of file ProjectSettings.cmake.

basis::qsplit = utilities.qsplit

Split quoted string of arguments.

Parameters:

[in] args Quoted string of arguments.

Returns:: Array of arguments.

See also:: tostring()

Definition at line 262 of file basis.py.

string basis::RELEASE = "r3148"

Complete version information as output by --version option.

Project version string used by print_version().

Definition at line 35 of file basis.cxx.

basis::SubprocessError = utilities.SubprocessError

Exception thrown when command execution failed.

See also:: sbia.basis.utilities.SubprocessError

Definition at line 240 of file basis.py.

basis::tostring = utilities.tostring

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:: qsplit()

Definition at line 252 of file basis.py.

string basis::VERSION = "0.0.0"

The version string given as "<major>.<minor>.<patch>".

Project version.

Definition at line 34 of file basis.cxx.

Files

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation