def add_reaction(self, state, event, reaction, *args, **kwargs):
"""Adds a reaction that may get triggered by the given event & state.
Reaction callbacks may (depending on how the state machine is ran) be
used after an event is processed (and a transition occurs) to cause the
machine to react to the newly arrived at stable state.
These callbacks are expected to accept three default positional
parameters (although more can be passed in via *args and **kwargs,
these will automatically get provided to the callback when it is
activated *ontop* of the three default). The three default parameters
are the last stable state, the new stable state and the event that
caused the transition to this new stable state to be arrived at.
The expected result of a callback is expected to be a new event that
the callback wants the state machine to react to. This new event
may (depending on how the state machine is ran) get processed (and
this process typically repeats) until the state machine reaches a
terminal state.
"""
if self.frozen:
raise excp.FrozenMachine()
if state not in self._states:
raise excp.NotFound("Can not add a reaction to event '%s' for an"
" undefined state '%s'" % (event, state))
if not six.callable(reaction):
raise ValueError("Reaction callback must be callable")
if event not in self._states[state]['reactions']:
self._states[state]['reactions'][event] = (reaction, args, kwargs)
else:
raise excp.Duplicate("State '%s' reaction to event '%s'"
" already defined" % (state, event))
def default_start_state(self, state):
if self.frozen:
raise excp.FrozenMachine()
if state not in self._states:
raise excp.NotFound("Can not set the default start state to"
" undefined state '%s'" % (state))
self._default_start_state = state
def add_transition(self, start, end, event, replace=False):
"""Adds an allowed transition from start -> end for the given event.
:param start: starting state
:param end: ending state
:param event: event that causes start state to
transition to end state
:param replace: replace existing event instead of raising a
:py:class:`~automaton.exceptions.Duplicate` exception
when the transition already exists.
"""
if self.frozen:
raise excp.FrozenMachine()
if start not in self._states:
raise excp.NotFound("Can not add a transition on event '%s' that"
" starts in a undefined state '%s'" %
(event, start))
if end not in self._states:
raise excp.NotFound("Can not add a transition on event '%s' that"
" ends in a undefined state '%s'" %
(event, end))
if self._states[start]['terminal']:
raise excp.InvalidState("Can not add a transition on event '%s'"
" that starts in the terminal state '%s'" %
(event, start))
if event in self._transitions[start] and not replace:
target = self._transitions[start][event]
if target.name != end:
raise excp.Duplicate(
"Cannot add transition from"
" '%(start_state)s' to '%(end_state)s'"
" on event '%(event)s' because a"
" transition from '%(start_state)s'"
" to '%(existing_end_state)s' on"
" event '%(event)s' already exists." % {
'existing_end_state': target.name,
'end_state': end,
'event': event,
'start_state': start
})
else:
target = _Jump(end, self._states[end]['on_enter'],
self._states[start]['on_exit'])
self._transitions[start][event] = target
def default_start_state(self, state):
"""Sets the *default* start state that the machine should use.
NOTE(harlowja): this will be used by ``initialize`` but only if that
function is not given its own ``start_state`` that overrides this
default.
"""
if self.frozen:
raise excp.FrozenMachine()
if state not in self._states:
raise excp.NotFound("Can not set the default start state to"
" undefined state '%s'" % (state))
self._default_start_state = state
def _pre_process_event(self, event):
current = self._current
if current is None:
raise excp.NotInitialized("Can not process event '%s'; the state"
" machine hasn't been initialized" %
event)
if self._states[current.name]['terminal']:
raise excp.InvalidState("Can not transition from terminal"
" state '%s' on event '%s'" %
(current.name, event))
if event not in self._transitions[current.name]:
raise excp.NotFound("Can not transition from state '%s' on"
" event '%s' (no defined transition)" %
(current.name, event))
def run_iter(self, event, initialize=True):
"""Returns a iterator/generator that will run the state machine.
This will keep a stack (hierarchy) of machines active and jumps through
them as needed (depending on which machine handles which event) during
the running lifecycle.
NOTE(harlowja): only one runner iterator/generator should be active for
a machine hierarchy, if this is not observed then it is possible for
initialization and other local state to be corrupted and causes issues
when running...
"""
machines = [self._machine]
if initialize:
machines[-1].initialize()
while True:
old_state = machines[-1].current_state
effect = self._process_event(machines, event)
new_state = machines[-1].current_state
try:
machine = effect.machine
except AttributeError:
pass
else:
if machine is not None and machine is not machines[-1]:
machine.initialize()
machines.append(machine)
try:
sent_event = yield (old_state, new_state)
except GeneratorExit:
break
if len(machines) == 1 and effect.terminal:
# Only allow the top level machine to actually terminate the
# execution, the rest of the nested machines must not handle
# events if they wish to have the root machine terminate...
break
if effect.reaction is None and sent_event is None:
raise excp.NotFound(_JUMPER_NOT_FOUND_TPL %
(new_state, old_state, event))
elif sent_event is not None:
event = sent_event
else:
cb, args, kwargs = effect.reaction
event = cb(old_state, new_state, event, *args, **kwargs)
def run_iter(self, event, initialize=True):
if initialize:
self._machine.initialize()
while True:
old_state = self._machine.current_state
reaction, terminal = self._machine.process_event(event)
new_state = self._machine.current_state
try:
sent_event = yield (old_state, new_state)
except GeneratorExit:
break
if terminal:
break
if reaction is None and sent_event is None:
raise excp.NotFound(_JUMPER_NOT_FOUND_TPL %
(new_state, old_state, event))
elif sent_event is not None:
event = sent_event
else:
cb, args, kwargs = reaction
event = cb(old_state, new_state, event, *args, **kwargs)
def initialize(self, start_state=None):
"""Sets up the state machine (sets current state to start state...).
:param start_state: explicit start state to use to initialize the
state machine to. If ``None`` is provided then
the machine's default start state will be used
instead.
"""
if start_state is None:
start_state = self._default_start_state
if start_state not in self._states:
raise excp.NotFound("Can not start from a undefined"
" state '%s'" % (start_state))
if self._states[start_state]['terminal']:
raise excp.InvalidState("Can not start from a terminal"
" state '%s'" % (start_state))
# No on enter will be called, since we are priming the state machine
# and have not really transitioned from anything to get here, we will
# though allow on_exit to be called on the event that causes this
# to be moved from...
self._current = _Jump(start_state, None,
self._states[start_state]['on_exit'])
def fun():
with self.driver.fsm_reset_on_error():
raise automaton_errors.NotFound('Oops!')
