scriptharness.script module

Scripts control the running of Actions.

scriptharness.script.LOGGER_NAME

str

logging.Logger name to use

scriptharness.script.LISTENER_PHASES

tuple

valid phases for Script.add_listener()

scriptharness.script.ALL_PHASES

tuple

valid phases for build_context()

scriptharness.script.PRE_RUN

str

the pre-run phase constant

scriptharness.script.POST_RUN

str

the post-run phase constant

scriptharness.script.PRE_ACTION

str

the pre-action phase constant

scriptharness.script.POST_ACTION

str

the post-action phase constant

scriptharness.script.RUN_ACTION

str

the run-action phase constant

class scriptharness.script.Context(script, config, logger, action, phase)

Bases: tuple

This is a namedtuple passed to each listener and action function so they can reference the config, logger, etc. easily. It contains pointers to the Script, config, logger, and phase. During action phases it also contains a pointer to the Action; during other phases, Context.action is None.

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__getstate__()

Exclude the OrderedDict from pickling

__repr__()

Return a nicely formatted representation string

action

Alias for field number 3

config

Alias for field number 1

logger

Alias for field number 2

phase

Alias for field number 4

script

Alias for field number 0

class scriptharness.script.Script(actions, template, name=u'root', **kwargs)

Bases: object

This maintains the context of the config + actions.

In general there is a single Script object per run, but the intent is to allow for parallel processing by instantiating multiple Script objects when it makes sense.

config

LoggingDict

the config for the script

actions

tuple

Action objects to run.

name

string

The name of the script

listeners

dict

Callbacks for run(). Listener functions can be set for each of LISTENER_PHASES.

logger

logging.Logger

the logger for the script

add_listener(listener, phase, action_names=None)

Add a callback for a specific script phase.

For pre and post_run, run at the beginning and end of the script, respectively.

For pre and post_action, run at the beginning and end of actions, respectively. If action_names are specified, only run before/after those action(s).

Parameters:
  • listener (function) – Function to call at the right time.
  • phase (str) – When to run the function. Choices in LISTENER_PHASES
  • action_names (iterable) – for pre/post action phase listeners, only run before/after these action(s).
build_config(template, cmdln_args=None, initial_config=None)

Create self.config from the parsed args.

If –dump-config is in the commandline arguments, the script will dump the config to screen and disk, and exit.

Parameters:
  • template (ConfigTemplate) – template to parse and validate the config.
  • cmdln_args (Optional[tuple]) – override the commandline args
  • initial_config (Optional[dict]) – initial config dict to apply.
Returns:

parsed_args from parse_args()
config = None
dict_to_config(config)

Convert the config dict to a LoggingDict.

This method is mainly here for subclassing; otherwise it could have easily stayed part of self.build_config().

end_message()

Log a message at the end of run()

Split out for subclassing; the string may end up moving elsewhere for localizability.

get_logger()

Get a logger to log messages.

This is not strictly needed, as python’s logging module will keep track of these loggers.

However, if we support structured logging as well as python logging, get_logger() may return one or the other depending on config.

This method may end up moving to the scriptharness module, and tracked in ScriptManager.

Returns:logging.Logger object.
log_enabled_actions()

Log enabled actions.

run()

Run all enabled actions.

run_action(action)

Run a specific action.

Parameters:

(Action object). (action) –

Raises:
save_config()

Save config to disk.

start_message()

Log a message at the end of __init__()

Split out for subclassing; the string may end up moving elsewhere for localizability.

verify_actions(actions)

Make sure actions consists of Action objects, with no duplicate names.

Then set self.actions to a namedtuple so we can find each action by name easily.

Parameters:actions (list of Action objects) – these are passed from __init__().
class scriptharness.script.StrictScript(*args, **kwargs)

Bases: scriptharness.script.Script

A subclass of Script that uses a ReadOnlyDict for config, and locks its attributes.

As for naming, there were the following choices:
  • Locking sounds like Logging;
  • ReadOnlyScript is a misnomer;
  • StrictScript is a tongue-twister.
_lock

bool

Similar to the ReadOnlyDict _lock. Once set, __setattr__ will raise if any attributes are changed/set.

dict_to_config(config)

Set self.config to a ReadOnlyDict and lock.

pre_config_lock()

Stub method for subclassing.

run()
scriptharness.script.build_context(script, phase, action=None)

Build context for functions called by Actions.

Parameters:
  • script (Script) – The calling Script
  • phase (str) – The current script phase (one of ALL_PHASES)
  • action (Optional[Action]) – The active Action, if applicable.
Raises:

scriptharness.exceptions.ScriptHarnessException – if there is an invalid phase.
Returns:

scriptharness.script.Context namedtuple.
scriptharness.script.enable_actions(parsed_args, action_list)

If parsed_args has action-related options, enable/disable actions as appropriate.

Parameters:
  • (argparse Namespace) (parsed_args) –
  • (list of Actions) (action_list) –
scriptharness.script.save_config(config, path)

Save the configuration file to path as json.

Parameters:
  • config (dict) – The config to save
  • path (str) – The path to write the config to