Table of Contents

Module: common qm/common.py
Functions   
close_file_on_exec
convert_from_dos_text
copy
format_exception
format_time
format_time_iso
format_traceback
get_doc_directory
get_lib_directory
get_share_directory
get_userid
get_username
html_to_text
load_class
load_module
make_unique_tag
open_temporary_file
open_temporary_file_fd
parse_assignment
parse_boolean
parse_time
parse_time_iso
read_assignments
split_argument_list
split_path_fully
wrap_lines
  close_file_on_exec 
close_file_on_exec ( fd )

Prevent fd from being inherited across exec.

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

This function has no effect on Windows.

  convert_from_dos_text 
convert_from_dos_text ( text )

Replace CRLF with LF in text.

  copy 
copy ( object )

Make a best-effort attempt to copy object.

returns
A copy of object, if feasible, or otherwise object.
  format_exception 
format_exception ( exc_info )

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_time 
format_time ( time_secs,  local_time_zone=1 )

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.
  format_time_iso 
format_time_iso ( time_secs=None )

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.
  format_traceback 
format_traceback ( exc_info )

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.
  get_doc_directory 
get_doc_directory ( *components )

Return a path to a file in the QM documentation file directory.

  get_lib_directory 
get_lib_directory ( *components )

Return the path to a file in the QM library directory.

  get_share_directory 
get_share_directory ( *components )

Return the path to a file in the QM data file directory.

  get_userid 
get_userid ()

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.

Exceptions   
QMException, "User ids not supported on this system."
  get_username 
get_username ()

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.

Exceptions   
PythonException("Error accessing win32 user database", * sys.exc_info() [ : 2 ] )
QMException, "Cannot determine user name."
  html_to_text 
html_to_text ( html,  width=72 )

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.
  load_class 
load_class (
        name,
        search_path=sys.path,
        load_path=sys.path,
        )

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.
Exceptions   
QMException, "%s is not a class" % name
QMException, "%s is not a fully-qualified class name" % name
QMException, "no class named %s in module %s" %( class_name, module_name )
  load_module 
load_module (
        name,
        search_path=sys.path,
        load_path=sys.path,
        )

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.
  make_unique_tag 
make_unique_tag ()

Return a unique tag string.

  open_temporary_file 
open_temporary_file ( mode="w+b",  suffix="" )

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.

  open_temporary_file_fd 
open_temporary_file_fd ( suffix="" )

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.
Exceptions   
QMException, qm.error("temp file error", file_name = file_name, exc_class = str(exc_info [ 0 ] ), exc_arg = str(exc_info [ 1 ] ) )
  parse_assignment 
parse_assignment ( assignment )

Parse an assignment of the form name=value.

aassignment
A string. The string should have the form name=value.
returns
A pair (name, value).
Exceptions   
QMException, qm.error( "invalid keyword assignment", argument = assignment )
  parse_boolean 
parse_boolean ( value )

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.
Exceptions   
ValueError, value
  parse_time 
parse_time ( time_string,  default_local_time_zone=1 )

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.

Exceptions   
ValueError
  parse_time_iso 
parse_time_iso ( time_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.
  read_assignments 
read_assignments ( file )

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.
  split_argument_list 
split_argument_list ( command )

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.
  split_path_fully 
split_path_fully ( path )

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.
  wrap_lines 
wrap_lines (
        text,
        columns=72,
        break_delimiter="\\",
        indent="",
        )

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.
Classes   

PythonException

A PythonException is a wrapper around a Python exception.

QMException

An exception generated directly by QM.

RcConfiguration

Interface object to QM configuration files.

UserError


Table of Contents

This document was automatically generated on Mon Jan 3 09:42:29 2005 by HappyDoc version 2.1