Package qm :: Module common
[hide private]
[frames] | no frames]

Module common
source code

Classes [hide private]
PythonException A 'PythonException' is a wrapper around a Python exception.
RcConfiguration Interface object to QM configuration files.
UserError  

Functions [hide private]
  close_file_on_exec(fd)
Prevent 'fd' from being inherited across 'exec'.
  convert_from_dos_text(text)
Replace CRLF with LF in 'text'.
  copy(object)
Make a best-effort attempt to copy 'object'.
  format_exception(exc_info)
Format an exception as structured text.
  format_time(time_secs, local_time_zone=1)
Generate a text format representing a date and time.
  format_time_iso(time_secs=None)
Generate a ISO8601-compliant formatted date and time.
  format_traceback(exc_info)
Format an exception traceback as structured text.
  get_doc_directory(*components)
Return a path to a file in the QM documentation file directory.
  get_lib_directory(*components)
Return the path to a file in the QM library directory.
  get_share_directory(*components)
Return the path to a file in the QM data file directory.
  get_userid()
Returns the current user id as an integer.
  get_username()
Returns the current username as a string.
  html_to_text(html, width=72)
Renders HTML to text in a simple way.
  load_class(name, search_path=sys.path, load_path=sys.path)
Load a Python class.
  load_module(name, search_path=sys.path, load_path=sys.path)
Load a Python module.
  make_unique_tag()
Return a unique tag string.
  open_temporary_file(mode="w+b", suffix="")
Create and open a temporary file.
  open_temporary_file_fd(suffix="")
Create and open a temporary file.
  parse_assignment(assignment)
Parse an 'assignment' of the form 'name=value'.
  parse_boolean(value)
Parse a boolean string.
  parse_string_list(value)
Parse a string list.
  parse_time(time_string, default_local_time_zone=1)
Parse a date and/or time string.
  parse_time_iso(time_string)
Parse a ISO8601-compliant formatted date and time.
  read_assignments(file)
Read assignments from a 'file'.
  split_argument_list(command)
Split a command into an argument list.
  split_path_fully(path)
Split 'path' into components.
  wrap_lines(text, columns=72, break_delimiter="\\", indent="")
Wrap lines in 'text' to 'columns' columns.

Variables [hide private]
__load_module_lock A lock used by load_module.
_unique_tag  
program_name The name of the application program.
rc The configuration stored in system and user rc files.

Function Details [hide private]

close_file_on_exec(fd)

source code 

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(text)

source code 
Replace CRLF with LF in 'text'.

copy(object)

source code 

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

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

format_exception(exc_info)

source code 

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

source code 

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

source code 

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

source code 

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

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

get_lib_directory(*components)

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

get_share_directory(*components)

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

get_userid()

source code 

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

get_username()

source code 

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

html_to_text(html, width=72)

source code 

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

source code 

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.

load_module(name, search_path=sys.path, load_path=sys.path)

source code 

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

source code 
Return a unique tag string.

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

source code 

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(suffix="")

source code 

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.

parse_assignment(assignment)

source code 

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

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

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

parse_boolean(value)

source code 

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_string_list(value)

source code 

Parse a string list.

'value' -- A string.

returns -- A list of strings.

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

parse_time(time_string, default_local_time_zone=1)

source code 

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_time_iso(time_string)

source code 

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(file)

source code 

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

source code 

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

source code 

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

source code 

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.

Variables Details [hide private]

__load_module_lock

A lock used by load_module.
Value:
<_RLock(None, 0)>                                                      
      

_unique_tag

Value:
0                                                                     
      

program_name

The name of the application program.
Value:
{}                                                                     
      

rc

The configuration stored in system and user rc files.
Value:
<qm.common.RcConfiguration instance at 0xb7bde14c>