Actions¶
Action is the way a StateMachine can cause things to happen in the outside world, and indeed they are the main reason why they exist at all.
The main point of introducing a state machine is for the actions to be invoked at the right times, depending on the sequence of events and the state of the guards.
Actions are most commonly performed on entry or exit of a state, although it is possible to add them before/after a transition.
There are several action callbacks that you can define to interact with a StateMachine in execution.
There are callbacks that you can specify that are generic and will be called when something changes and are not bounded to a specific state or event:
before_transition()
on_exit_state()
on_transition()
on_enter_state()
after_transition()
The following example can get you an overview of the “generic” callbacks available:
>>> from statemachine import StateMachine, State
>>> class ExampleStateMachine(StateMachine):
... initial = State(initial=True)
... final = State(final=True)
...
... loop = initial.to.itself()
... go = initial.to(final)
...
... def before_transition(self, event, state):
... print(f"Before '{event}', on the '{state.id}' state.")
... return "before_transition_return"
...
... def on_transition(self, event, state):
... print(f"On '{event}', on the '{state.id}' state.")
... return "on_transition_return"
...
... def on_exit_state(self, event, state):
... print(f"Exiting '{state.id}' state from '{event}' event.")
...
... def on_enter_state(self, event, state):
... print(f"Entering '{state.id}' state from '{event}' event.")
...
... def after_transition(self, event, state):
... print(f"After '{event}', on the '{state.id}' state.")
>>> sm = ExampleStateMachine() # On initialization, the machine run a special event `__initial__`
Entering 'initial' state from '__initial__' event.
>>> sm.loop()
Before 'loop', on the 'initial' state.
Exiting 'initial' state from 'loop' event.
On 'loop', on the 'initial' state.
Entering 'initial' state from 'loop' event.
After 'loop', on the 'initial' state.
['before_transition_return', 'on_transition_return']
>>> sm.go()
Before 'go', on the 'initial' state.
Exiting 'initial' state from 'go' event.
On 'go', on the 'initial' state.
Entering 'final' state from 'go' event.
After 'go', on the 'final' state.
['before_transition_return', 'on_transition_return']
See also
All actions and Guards support multiple method signatures. They follow the Dynamic dispatch method calling implemented on this library.
State actions¶
For each defined State, you can declare enter
and exit
callbacks.
Bind state actions by naming convention¶
Callbacks by naming convention will be searched on the StateMachine and on the model, using the patterns:
on_enter_<state.id>()
on_exit_<state.id>()
>>> from statemachine import StateMachine, State
>>> class ExampleStateMachine(StateMachine):
... initial = State(initial=True)
...
... loop = initial.to.itself()
...
... def on_enter_initial(self):
... pass
...
... def on_exit_initial(self):
... pass
Bind state actions using params¶
Use the enter
or exit
params available on the State
constructor.
>>> from statemachine import StateMachine, State
>>> class ExampleStateMachine(StateMachine):
... initial = State(initial=True, enter="entering_initial", exit="leaving_initial")
...
... loop = initial.to.itself()
...
... def entering_initial(self):
... pass
...
... def leaving_initial(self):
... pass
Hint
It’s also possible to use an event name as action.
Be careful to not introduce recursion errors that will raise RecursionError
exception.
Bind state actions using decorator syntax¶
>>> from statemachine import StateMachine, State
>>> class ExampleStateMachine(StateMachine):
... initial = State(initial=True)
...
... loop = initial.to.itself()
...
... @initial.enter
... def entering_initial(self):
... pass
...
... @initial.exit
... def leaving_initial(self):
... pass
Transition actions¶
For each Event, you can register before
, on
, and after
callbacks.
Declare transition actions by naming convention¶
The action will be registered for every Transition associated with the event.
Callbacks by naming convention will be searched on the StateMachine and the model, using the patterns:
before_<event>()
on_<event>()
after_<event>()
>>> from statemachine import StateMachine, State
>>> class ExampleStateMachine(StateMachine):
... initial = State(initial=True)
...
... loop = initial.to.itself()
...
... def before_loop(self):
... pass
...
... def on_loop(self):
... pass
...
... def after_loop(self):
... pass
...
Bind transition actions using params¶
>>> from statemachine import StateMachine, State
>>> class ExampleStateMachine(StateMachine):
... initial = State(initial=True)
...
... loop = initial.to.itself(before="just_before", on="its_happening", after="loop_completed")
...
... def just_before(self):
... pass
...
... def its_happening(self):
... pass
...
... def loop_completed(self):
... pass
Hint
It’s also possible to use an event name as action to chain transitions.
Be careful to not introduce recursion errors, like loop = initial.to.itself(after="loop")
, that will raise RecursionError
exception.
Bind transition actions using decorator syntax¶
The action will be registered for every Transition in the list associated with the event.
>>> from statemachine import StateMachine, State
>>> class ExampleStateMachine(StateMachine):
... initial = State(initial=True)
...
... loop = initial.to.itself()
...
... @loop.before
... def just_before(self):
... pass
...
... @loop.on
... def its_happening(self):
... pass
...
... @loop.after
... def loop_completed(self):
... pass
...
... @loop.cond
... def should_we_allow_loop(self):
... return True
...
... @loop.unless
... def should_we_block_loop(self):
... return False
Declare an event while also giving an “on” action using the decorator syntax¶
You can also declare an event while also adding a callback:
>>> from statemachine import StateMachine, State
>>> class ExampleStateMachine(StateMachine):
... initial = State(initial=True)
...
... @initial.to.itself()
... def loop(self):
... print("On loop")
... return 42
Note that with this syntax, the resulting loop
that is present on the ExampleStateMachine.loop
namespace is not a simple method, but an Event trigger. So it only executes if the
StateMachine is in the right state.
So, you can use the event-oriented approach:
>>> sm = ExampleStateMachine()
>>> sm.send("loop")
On loop
42
Other callbacks¶
In addition to Actions, you can specify Validators and guards that are checked before a transition is started. They are meant to stop a transition to occur.
See also
See Guards and Validators.
Ordering¶
Actions and Guards will be executed in the following order:
validators()
(attached to the transition)conditions()
(attached to the transition)unless()
(attached to the transition)before_transition()
before_<event>()
on_exit_state()
on_exit_<state.id>()
on_transition()
on_<event>()
on_enter_state()
on_enter_<state.id>()
after_<event>()
after_transition()
Return values¶
Currently only certain actions’ return values will be combined as a list and returned for a triggered transition:
before_transition()
before_<event>()
on_transition()
on_<event>()
Note that None
will be used if the action callback does not return anything, but only when it is
defined explicitly. The following provides an example:
>>> class ExampleStateMachine(StateMachine):
... initial = State(initial=True)
...
... loop = initial.to.itself()
...
... def before_loop(self):
... return "Before loop"
...
... def on_transition(self):
... pass
...
... def on_loop(self):
... return "On loop"
...
>>> sm = ExampleStateMachine()
>>> sm.loop()
['Before loop', None, 'On loop']
For RTC model, only the main event will get its value list, while the chained ones simply get
None
returned. For Non-RTC model, results for every event will always be collected and returned.
Dynamic dispatch¶
StateMachine implements a custom dispatch mechanism on all those available Actions and
Guards. This means that you can declare an arbitrary number of *args
and **kwargs
, and the
library will match your method signature of what’s expected to receive with the provided arguments.
This means that if on your on_enter_<state.id>()
or on_<event>()
method, you need to know
the source
(State), or the event
(Event), or access a keyword
argument passed with the trigger, just add this parameter to the method and It will be passed
by the dispatch mechanics.
In other words, if you implement a method to handle an event and don’t declare any parameter, you’ll be fine, if you declare an expected parameter, you’ll also be covered.
For your convenience, all these parameters are available for you on any Action or Guard:
*args
All positional arguments provided on the Event.
**kwargs
All keyword arguments provided on the Event.
event_data
A reference to EventData instance.
event
The Event that was triggered.
source
state
The current State of the state machine.
target
The destination State of the transition.
model
A reference to the underlying model that holds the current State.
transition
The Transition instance that was activated by the Event.
So, you can implement Actions and Guards like these, but this list is not exhaustive, it’s only to give you a few examples… any combination of parameters will work, including extra parameters that you may inform when triggering an Event:
def action_or_guard_method_name(self):
pass
def action_or_guard_method_name(self, model):
pass
def action_or_guard_method_name(self, event):
pass
def action_or_guard_method_name(self, *args, event_data, event, source, state, model, **kwargs):
pass
See also
See the example All actions machine for a complete example of order resolution of callbacks.