scriptharness package

Module contents

Scriptharness is a python scripting harness or framework.

Scriptharness’ core principles are:
  • Full logging.
  • Flexible configuration.
  • Modular actions.
The top-level module has two main purposes:
  1. to serve shortcuts for simple scripts. A single import, and a few function calls should serve for simple workflows.
  2. the ScriptManager can keep track of all Script objects if and when a script requires multiple Script objects.
scriptharness.get_script(*args, **kwargs)

This will retrieve an existing script or create one and return it.

Parameters:
  • actions (tuple of Actions) – When creating a new Script, this is required. When retrieving an existing script, this is ignored/optional.
  • parser (argparse.ArgumentParser) – When creating a new Script, this is required. When retrieving an existing script, this is ignored/optional.
  • name (Optional[str]) – The name of the script to retrieve/create. Defaults to “root”. This is a keyword argument, so use name=NAME
  • **kwargs – kwargs to pass to MANAGER.get_script(); these will be passed to Script.__init__() when creating a new Script. When retrieving an existing script, this is ignored/optional.
Returns:

The Script instance.
scriptharness.get_config(name=u'root')

This will return the config from an existing script.

Parameters:name (Optional[str]) – The name of the script to get the config from. Defaults to “root”.
Raises:scriptharness.exceptions.ScriptHarnessException – if there is no script of name name.
Returns:config – By default scriptharness.structures.LoggingDict
Return type:dict
scriptharness.get_actions(all_actions)

Build a tuple of Action objects for the script.

Parameters:all_actions (data structure) – ordered mapping of action_name:enabled bool, as accepted by iterate_pairs()
Returns:tuple of Action objects
scriptharness.get_actions_from_list(all_actions, default_actions=None)

Helper method to generate the ordered mapping for get_actions().

Parameters:
  • all_actions (list) – ordered list of all action names
  • default_actions (Optional[list]) – actions that are enabled by default
Returns:

tuple of Action objects
scriptharness.get_logger(name=u'root')

This will return the logger from an existing script.

This function isn’t strictly needed, since the logging module keeps track of loggers for you. However, if/when scriptharness supports multiple parallel Script objects, and if/when scriptharness supports structured logging outside of the python logging module, this function will become more important.

Parameters:name (Optional[str]) – The name of the script to get the logger from. Defaults to “root”.
Raises:scriptharness.exceptions.ScriptHarnessException – if there is no script of name name.
Returns:logger (logging.Logger)
scriptharness.get_config_template(template=None, all_actions=None, definition=None)

Create a script ConfigTemplate.

If template is not defined, it will take the definition (defaults to DEFAULT_CONFIG_DEFINITION) and create a new ConfigTemplate. Otherwise it uses template.

If all_actions is defined, it will add an action ConfigTemplate to the template.

Parameters:
  • template (Optional[ConfigTemplate]) – the ConfigTemplate to optionally append the action_template to. Defaults to None.
  • all_actions (Optional[list]) – list of actions to generate an action ConfigTemplate. Defaults to None.
  • definition (Optional[dict]) – config definition to prepopulate the ConfigTemplate with. Defaults to DEFAULT_CONFIG_DEFINITION.
Returns:

ConfigTemplate
scriptharness.prepare_simple_logging(path, mode=u'w', logger_name=u'', level=20, formatter=None)

Create a unicode-friendly logger.

By default it’ll create the root logger with a console handler; if passed a path it’ll also create a file handler. Both handlers will have a unicode-friendly formatter.

This function is intended to be called a single time. If called a second time, beware creating multiple console handlers or multiple file handlers writing to the same file.

Parameters:
  • path (Optional[str]) – path to the file log. If this isn’t set, don’t create a file handler. Default ‘’
  • mode (Optional[char]) – the mode to open the file log. Default ‘w’
  • logger_name (Optional[str]) – the name of the logger to use. Default ‘’
  • level (Optional[int]) – the level to log. Default DEFAULT_LEVEL
  • formatter (Optional[Formatter]) – a logging Formatter to use; to handle unicode, subclass UnicodeFormatter.
Returns:

logger (Logger object). This is also easily retrievable via logging.getLogger(logger_name).
scriptharness.set_action_class(action_class)
By default new actions use the scriptharness.actions.Action class.
Override here.
Parameters:action_class (class) – use this class for new actions.
scriptharness.set_script_class(script_class)

By default new scripts use the scriptharness.script.Script class. Override here.

Parameters:script_class (class) – use this class for new scripts.