Module common

Format an exception as structured text.

'exc_info' -- A three-element tuple containing exception info, of the form '(type, value, traceback)'.

returns -- A string containing a the formatted exception.

Format an exception traceback as structured text.

'exc_info' -- A three-element tuple containing exception info, of the form '(type, value, traceback)'.

returns -- A string containing a the formatted traceback.

Load a Python module.

'name' -- The fully-qualified name of the module to load, for instance 'package.subpackage.module'.

'search_path' -- A sequence of directories. These directories are searched to find the module.

'load_path' -- The setting of 'sys.path' when the module is loaded.

returns -- A module object.

raises -- 'ImportError' if the module cannot be found.

Load a Python class.

'name' -- The fully-qualified (including package and module names) class name, for instance 'package.subpackage.module.MyClass'. The class must be at the top level of the module's namespace, i.e. not nested in another class.

'search_path' -- A sequence of directories. These directories are searched to find the module.

'load_path' -- The setting of 'sys.path' when the module is loaded.

returns -- A class object.

raises -- 'ImportError' if the module containing the class can't be imported, or if there is no class with the specified name in that module, or if 'name' doesn't correspond to a class.

Split 'path' into components.

Uses 'os.path.split' recursively on the directory components of 'path' to separate all path components.

'path' -- The path to split.

returns -- A list of path componets.

Create and open a temporary file.

'suffix' -- The last part of the temporary file name, as for Python's 'mktemp' function.

The file is open for reading and writing. The caller is responsible for deleting the file when finished with it.

returns -- A pair '(file_name, file_descriptor)' for the temporary file.

Create and open a temporary file.

'mode' -- The mode argument to pass to 'fopen'.

'suffix' -- The last part of the temporary file name, as for Python's 'mktemp' function.

Like 'open_temporary_file_fd', except that the second element of the return value is a file object.

Prevent 'fd' from being inherited across 'exec'.

'fd' -- A file descriptor, or object providing a 'fileno()' method.

This function has no effect on Windows.

Make a best-effort attempt to copy 'object'.

returns -- A copy of 'object', if feasible, or otherwise 'object'.

Wrap lines in 'text' to 'columns' columns.

'text' -- The text to wrap.

'columns' -- The maximum number of columns of text.

'break_delimiter' -- Text to place at the end of each broken line (may be an empty string).

'indent' -- Text to place at the start of each line. The length of 'indent' does not count towards 'columns'.

returns -- The wrapped text.

Generate a text format representing a date and time.

The output is in the format "YYYY-MM-DD HH:MM ZZZ".

'time_secs' -- The number of seconds since the start of the UNIX epoch, UTC.

'local_time_zone' -- If true, format the time in the local time zone. Otherwise, format it as UTC.

Generate a ISO8601-compliant formatted date and time.

The output is in the format "YYYY-MM-DDThh:mm:ss+TZ", where TZ is a timezone specifier. We always normalize to UTC (and hence always use the special timezone specifier "Z"), to get proper sorting behaviour.

'time_secs' -- The time to be formatted, as returned by e.g. 'time.time()'. If 'None' (the default), uses the current time.

returns -- The formatted time as a string.

Parse a ISO8601-compliant formatted date and time.

See also 'format_time_iso'.

'time_string' -- The string to be parsed, as returned by e.g. 'format_time_iso'.

returns -- The time as a float, like that returned by 'time.time'.

Split a command into an argument list.

'command' -- A string containing a shell or similar command.

returns -- An argument list obtained by splitting the command.

Parse a boolean string.

'value' -- A string.

returns -- True if 'value' is a true string, false if 'value' is a false string.

raises -- 'ValueError' if 'value' is neither a true string, nor a false string.

Parse a string list.

'value' -- A string.

returns -- A list of strings.

raises -- 'ValueError' if 'value' contains unbalanced quotes.

Parse a date and/or time string.

'time_string' -- A string representing a date and time in the format returned by 'format_time'. This function makes a best-effort attempt to parse incomplete strings as well.

'default_local_time_zone' -- If the time zone is not specified in 'time_string' and this parameter is true, assume the time is in the local time zone. If this parameter is false, assume the time is UTC.

returns -- An integer number of seconds since the start of the UNIX epoch, UTC.

Only UTC and the current local time zone may be specified explicitly in 'time_string'.

Parse an 'assignment' of the form 'name=value'.

'aassignment' -- A string. The string should have the form 'name=value'.

returns -- A pair '(name, value)'.

Read assignments from a 'file'.

'file' -- A file object containing the context. When the file is read, leading and trailing whitespace is discarded from each line in the file. Then, lines that begin with a '#' and lines that contain no characters are discarded. All other lines must be of the form 'NAME=VALUE' and indicate an assignment to the context variable 'NAME' of the indicated 'VALUE'.

returns -- A dictionary mapping each of the indicated 'NAME's to its corresponding 'VALUE'. If multiple assignments to the same 'NAME' are present, only the 'VALUE' from the last assignment is stored.

Returns the current username as a string.

This is our best guess as to the username of the user who is actually logged in, as opposed to the effective user id used for running tests.

If the username cannot be found, raises a 'QMException'.

Returns the current user id as an integer.

This is the real user id, not the effective user id, to better track who is actually running the tests.

If the user id cannot be found or is not defined, raises a 'QMException'.

Renders HTML to text in a simple way.

'html' -- A string containing the HTML code to be rendered.

'width' -- Column at which to word-wrap. Default 72.

returns -- A string containing a plain text rendering of the HTML.