Common utilities

General functions and classes shared in the codebase

General functions

xl.common.log_exception(log=<logging.Logger object>, message='Exception caught!')

Convenience function to log an exception + traceback

Parameters:
  • log – the logger object to use. important to specify so that it will be logged under the right module name.
  • message – a message describing the error condition.
xl.common.to_unicode(x, default_encoding=None)

Force getting a unicode string from any object.

xl.common.order_poset(items)
Parameters:items (list of PosetItem) – poset to order

Filesystem

xl.common.open_file(path)

Opens a file or folder using the system configured program

xl.common.open_file_directory(path)

Opens the parent directory of a file, selecting the file if possible.

xl.common.walk(root)

Walk through a Gio directory, yielding each file

Files are enumerated in the following order: first the directory, then the files in that directory. Once one directory’s files have all been listed, it moves on to the next directory. Order of files within a directory and order of directory traversal is not specified.

Parameters:root – a gio.File representing the directory to walk through
Returns:a generator object
Return type:gio.File
xl.common.walk_directories(root)

Walk through a Gio directory, yielding each subdirectory

Parameters:root – a gio.File representing the directory to walk through
Returns:a generator object
Return type:gio.File

Decorators

xl.common.threaded(func)

A decorator that will make any function run in a new thread

Parameters:func – the function to run threaded
xl.common.synchronized(func)

A decorator to make a function synchronized - which means only one thread is allowed to access it at a time.

This only works on class functions, and creates a variable in the instance called _sync_lock.

If this function is used on multiple functions in an object, they will be locked with respect to each other. The lock is re-entrant.

xl.common.profileit(func)

Decorator to profile a function

xl.common.classproperty(function)

Decorator allowing for class property access

xl.common.cached(limit)

Decorator to make a function’s results cached does not cache if there is an exception.

Note

This probably breaks on functions that modify their arguments

Classes

exception xl.common.VersionError(message)
class xl.common.LimitedCache(limit)

Bases: UserDict.DictMixin

Simple cache that acts much like a dict, but has a maximum # of items

class xl.common.TimeSpan(span)

Calculates the number of days, hours, minutes, and seconds in a time span

Parameters:span (float) – Time span in seconds
days = 0

number of days

hours = 0

number of hours

minutes = 0

number of minutes

seconds = 0

number of seconds

class xl.common.MetadataList(iterable=[], metadata=[])

Like a list, but also associates an object of metadata with each entry.

(get|set|del)_meta_key are the metadata interface - they allow the metadata to act much like a dictionary, with a few optimizations.

List aspects that are not supported:
  • sort
  • comparisons other than equality
  • multiply
class xl.common.ProgressThread

A basic thread with progress updates

run()

Override and make sure that the ‘progress-update’ signal is emitted regularly with the progress

stop()

Stops the thread

class xl.common.PosetItem(name, after, priority, value=None)
Parameters:
  • name (string) – unique identifier for this item
  • after (list of string) – which items this item comes after
  • priority (int) – tiebreaker, higher values come later
  • value – arbitrary data associated with the item