Scripts and Actions

Scripts and Phases

The Script is generally what one would think of as the script itself: it parses the commandline arguments and runs each enabled Action. There’s the possibility of enabling running multiple Scripts in parallel at some point.

It’s possible to add callbacks, called listeners, to the Script. These get triggered in phases. The list of phases are in ALL_PHASES; the phases that allow listeners are in LISTENER_PHASES.

  • The PRE_RUN phase is first, before any actions are run.
  • The PRE_ACTION phase happens before every enabled action, but a listener can be added to a subset of those actions if desired.
  • The ACTION phase is when the enabled Action is run. No listener can be added to the ACTION phase.
  • The POST_ACTION phase happens after every enabled action, but a listener can be added to a subset of those actions if desired.
  • The POST_RUN phase happens after all enabled actions are run.
  • The POST_FATAL phase happens after a ScriptHarnessFatal exception is raised, but before the script exits.

Contexts

Each listener or Action function is passed a Context. The Context is a namedtuple with the following properties:

  • script (Script): the Script calling the function
  • config (dict): by default this is a LoggingDict
  • logger (logging.Logger): the logger for the Script
  • action (Action): this is only defined during the RUN_ACTION, PRE_ACTION, and POST_ACTION phases; it is None in the other phases.
  • phase (str): this will be one of PRE_RUN, POST_RUN, PRE_ACTION, POST_ACTION, or POST_FATAL, depending on which phase we’re in.

The logger and config (and to a lesser degree, the script and action) objects are all available to each function called for convenience and consistency.

Actions

Each action can be enabled or disabled via commandline options (see Enabling and Disabling Actions). By default they look for a function with the same name as the action name, with - replaced by _. However, any function or method may be specified as the Action.function.

When run, the Action calls the Action.function with a Context. The function should raise ScriptHarnessError on error, or ScriptHarnessFatal on fatal error.

Afterwards, the Action.history contains the return_value, status, start_time, and end_time.