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 theACTION
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
, andPOST_ACTION
phases; it isNone
in the other phases. - phase (str): this will be one of
PRE_RUN
,POST_RUN
,PRE_ACTION
,POST_ACTION
, orPOST_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
.