xylem package

Submodules

xylem.exception module

Exception classes for error handling xylem.

exception xylem.exception.DownloadFailure

Bases: builtins.Exception

Failure downloading data for I/O or other reasons.

exception xylem.exception.InstallerNotAvailable

Bases: builtins.Exception

Failure indicating a installer is not installed.

exception xylem.exception.InvalidDataError

Bases: builtins.Exception

Data is not in valid xylem format.

exception xylem.exception.InvalidPluginError

Bases: builtins.Exception

Plugin loaded from an entry point does not have the right type/data.

xylem.load_url module

Helper to download content from url.

xylem.load_url.load_url(url, retry=2, retry_period=1, timeout=10)

Load a given url with retries, retry_periods, and timeouts.

Parameters:
  • url (str) – URL to load and return contents of
  • retry (int) – number of times to retry the url on 503 or timeout
  • retry_period (float) – time to wait between retries in seconds
  • timeout (float) – timeout for opening the URL in seconds
Retunrs:

loaded data as string
Return type:

str
Raises DownloadFailure:
 

if loading fails even after retries

xylem.log_utils module

xylem.log_utils.debug(msg, file=None, *args, **kwargs)

Print debug to console or file.

Works like print(), optionally uses terminal colors and tries to handle unicode correctly by encoding to utf-8 before printing. Can be enabled or disabled with enable_debug().

xylem.log_utils.enable_debug(state=True)

En- or disable printing debug output to console.

xylem.log_utils.enable_verbose(state=True)

En- or disable printing verbose output to console.

xylem.log_utils.error(msg, file=None, exit=False, *args, **kwargs)

Print error statement and optionally exit.

Works like print(), optionally uses terminal colors and tries to handle unicode correctly by encoding to utf-8 before printing.

xylem.log_utils.info(msg, file=None, *args, **kwargs)

Print info to console or file.

Works like print(), optionally uses terminal colors and tries to handle unicode correctly by encoding to utf-8 before printing.

xylem.log_utils.is_debug()

Return true if xylem is set to debug console output.

xylem.log_utils.is_verbose()

Return true if xylem is set to verbose console output.

xylem.log_utils.warning(msg, file=None, *args, **kwargs)

Print warning to console or file.

Works like print(), optionally uses terminal colors and tries to handle unicode correctly by encoding to utf-8 before printing. Can be enabled or disabled with enable_debug().

xylem.lookup module

xylem.plugin_utils module

Helpers for loading plugin definitions.

class xylem.plugin_utils.PluginBase

Bases: builtins.object

Abstract base class for all plugin classes.

Plugin classes must define the name property. This name is used in other parts of the system. For example for installer plugins the installer name "apt" is used in rules definitions. The name of plugin classes is distinct from the plugin name from the plugin definition. The latter is only used to refer to the plugin definitions themselves and (de-)activate specific plugins. All loaded plugins of one kind are unique by the plugin class name.

name

Name of the plugin object.

xylem.plugin_utils.get_plugin_list(kind, base_class, group)

Load plugins form entry points.

Load the plugins of given kind from entry points group, instantiating objects and ignoring duplicates. The entry points must be valid plugin definitions (see verify_plugin_definition()). The list of plugins is free of duplicates by plugin class name (not plugin name).

Parameters:
  • kind (str) – kind of plugin (e.g. “installer”)
  • base_class – (abstract) base class plugins (must implement PluginBase)
  • group – entry point group to load plugins from
Returns:

list of the loaded and instantiated plugin classes
Return type:

list
xylem.plugin_utils.verify_plugin_class(class_, base_class)

Verify class from plugin definition.

Raises ValueError:
 if class is invalid
xylem.plugin_utils.verify_plugin_definition(definition, kind, base_class)

Verify plugin definition.

Parameters:
  • definition (dict) – definition of plugin as loaded from entry point
  • kind (str) – kind of plugin (e.g. “installer”)
  • base_class (type) – (abstract) base class plugins must derive from
Raises InvalidPluginError:
 

if plugin definition is invalid
xylem.plugin_utils.verify_plugin_description(decription)

Verify decription from plugin definition.

Raises ValueError:
 if decription is invalid
xylem.plugin_utils.verify_plugin_name(name)

Verify name from plugin definition.

Raises ValueError:
 if name is invalid

xylem.resolve module

xylem.resolve.resolve(xylem_keys, prefix=None, os_override=None, all_keys=False)

xylem.terminal_color module

Module to enable color terminal output.

class xylem.terminal_color.ColorTemplate(template)

Bases: string.Template

delimiter = '@'
pattern = re.compile('\n \\@(?:\n (?P<escaped>\\@) | # Escape sequence of two delimiters\n (?P<named>[_a-z][_a-z0-9]*) | # delimiter and a Python identifier\n {(?P<braced>[_a-z][_a-z0-9]*)} | , re.IGNORECASE|re.VERBOSE)
xylem.terminal_color.ansi(key)

Return the escape sequence for a given ansi color key.

xylem.terminal_color.disable_ANSI_colors()

Disable output of ANSI color serquences with ansi().

Set all the ANSI escape sequences to empty strings, which effectively disables console colors.

xylem.terminal_color.enable_ANSI_colors()

Enable output of ANSI color serquences with ansi().

Colors are enabled by populating the global module dictionary _ansi with ANSI escape sequences.

xylem.terminal_color.fmt(msg)

Replace color annotations with ansi escape sequences.

xylem.terminal_color.sanitize(msg)

Sanitize the existing msg, use before adding color annotations.

xylem.text_utils module

Utility module for dealing with unicode/str/bytes in a uniform way.

This has been inspired by parts of the kitchen package, which is not py3 compatible to date.

xylem.text_utils.to_bytes(obj, encoding='utf-8', errors='replace')

Helper for converting to encoded byte-strings in py2 and py3.

xylem.text_utils.to_str(obj, encoding='utf-8', errors='replace')

Helper for converting to (unicode) text in py2 and py3.

xylem.update module

Implements the update functionality.

This includes the functions to collect and process source files. Part of this process is to load and run the spec parser, which are given by name in the source files.

xylem.update.update(prefix=None, dry_run=False)

Update the xylem cache.

If the prefix is set then the source lists are searched for in the prefix. If the prefix is not set (None) or the source lists are not found in the prefix, then the default, builtin source list is used.

Parameters:
  • prefix (str or None) – The config and cache prefix, usually ‘/’ or someother prefix
  • dry_run (bool) – If True, then no actual action is taken, only pretend to

xylem.util module

Provides common utility functions for xylem.

xylem.util.add_global_arguments(parser)
class xylem.util.change_directory(directory='')

Bases: builtins.object

xylem.util.create_temporary_directory(prefix_dir=None)

Create a temporary directory and return its location.

xylem.util.custom_exception_handler(type, value, tb)
xylem.util.dump_yaml(data, inline=False)

Dump data to unicode string.

xylem.util.handle_global_arguments(args)
xylem.util.load_yaml(data)

Parse a unicode string containing yaml.

This calls yaml.load(data) but makes sure unicode is handled correctly.

See yaml.load().

Raises yaml.YAMLError:
 if parsing fails
xylem.util.pdb_hook()
xylem.util.print_exc(formated_exc)
xylem.util.raise_from(exc_type, exc_args, from_exc)

Raise new exception directly caused by from_exc.

On py3, this is equivalent to raise exc_type(exc_args) from from_exc and on py2 the messages are composed manually to retain the arguments of from_exc as well as the stack trace.

xylem.util.read_stdout(cmd)
class xylem.util.redirected_stdio

Bases: builtins.object

class xylem.util.temporary_directory(prefix='')

Bases: builtins.object

Module contents