Transitions and events¶

A state machine is typically composed of a set of State, Transition, Event, and Actions. A state is a representation of the system’s current condition or behavior. A transition represents the change in the system’s state in response to an event or condition. An event is a trigger that causes the system to transition from one state to another, and action is any side-effect, which is the way a StateMachine can cause things to happen in the outside world.

Consider this traffic light machine as an example:

TrafficLightMachine

There’re three transitions, one starting from green to yellow, another from yellow to red, and another from red back to green. All these transitions are triggered by the same Event called cycle.

This state machine could be expressed in python-statemachine as:

"""

-------------------
Reusing transitions
-------------------

This example helps to turn visual the different compositions of how to declare
and bind :ref:`transitions` to :ref:`event`.

.. note::

    Even sharing the same transition instance, only the transition actions associated with the
    event will be called.


TrafficLightMachine
   The same transitions are bound to more than one event.

TrafficLightIsolatedTransitions
    We define new transitions, thus, isolating the connection
    between states.

"""

from statemachine import State
from statemachine import StateMachine


class TrafficLightMachine(StateMachine):
    "A traffic light machine"

    green = State(initial=True)
    yellow = State()
    red = State()

    slowdown = green.to(yellow)
    stop = yellow.to(red)
    go = red.to(green)

    cycle = slowdown | stop | go

    def before_slowdown(self):
        print("Slowdown")

    def before_cycle(self, event: str, source: State, target: State, message: str = ""):
        message = ". " + message if message else ""
        return f"Running {event} from {source.id} to {target.id}{message}"

    def on_enter_red(self):
        print("Don't move.")

    def on_exit_red(self):
        print("Go ahead!")


# %%
# Run a transition

sm = TrafficLightMachine()
sm.send("cycle")


# %%


class TrafficLightIsolatedTransitions(StateMachine):
    "A traffic light machine"

    green = State(initial=True)
    yellow = State()
    red = State()

    slowdown = green.to(yellow)
    stop = yellow.to(red)
    go = red.to(green)

    cycle = green.to(yellow) | yellow.to(red) | red.to(green)

    def before_slowdown(self):
        print("Slowdown")

    def before_cycle(self, event: str, source: State, target: State, message: str = ""):
        message = ". " + message if message else ""
        return f"Running {event} from {source.id} to {target.id}{message}"

    def on_enter_red(self):
        print("Don't move.")

    def on_exit_red(self):
        print("Go ahead!")


# %%
# Run a transition

sm2 = TrafficLightIsolatedTransitions()
sm2.send("cycle")

In line 18, you can say that this code defines three transitions:

green.to(yellow)
yellow.to(red)
red.to(green)

And these transitions are assigned to the Event cycle defined at the class level.

Transitions¶

In an executing state machine, a Transition is a transfer from one state to another. In a StateMachine, a Transition tells us what happens when an Event occurs.

Tip

A transition can define Actions that will be executed whenever that transition is executed.

Transitions can be filtered with Guards allowing you to add conditions when a transition may be executed.

An action associated with an event (before, on, after), will be assigned to all transitions bounded that uses the event as trigger.

Hint

Usually you don’t need to import and use a Transition class directly in your code, one of the most powerful features of this library is how transitions and events can be expressed linking directly from/to State instances.

Self transition¶

A transition that goes from a state to itself.

Syntax:

>>> draft = State("Draft")

>>> draft.to.itself()
TransitionList([Transition(State('Draft', ...

Internal transition¶

It’s like a Self transition.

But in contrast to a self-transition, no entry or exit actions are ever executed as a result of an internal transition.

Syntax:

>>> draft = State("Draft")

>>> draft.to.itself(internal=True)
TransitionList([Transition(State('Draft', ...

Example:

>>> class TestStateMachine(StateMachine):
...     initial = State(initial=True)
...
...     external_loop = initial.to.itself(on="do_something")
...     internal_loop = initial.to.itself(internal=True, on="do_something")
...
...     def __init__(self):
...         self.calls = []
...         super().__init__()
...
...     def do_something(self):
...         self.calls.append("do_something")
...
...     def on_exit_initial(self):
...         self.calls.append("on_exit_initial")
...
...     def on_enter_initial(self):
...         self.calls.append("on_enter_initial")

Usage:

>>> sm = TestStateMachine()

>>> sm._graph().write_png("docs/images/test_state_machine_internal.png")

>>> sm.calls.clear()

>>> sm.external_loop()

>>> sm.calls
['on_exit_initial', 'do_something', 'on_enter_initial']

>>> sm.calls.clear()

>>> sm.internal_loop()

>>> sm.calls
['do_something']

TestStateMachine

Note

The internal transition is represented the same way as an entry/exit action, where the event name is used to describe the transition.

Event¶

An event is an external signal that something has happened. They are send to a state machine and allow the state machine to react.

An event starts a Transition, which can be thought of as a “cause” that initiates a change in the state of the system.

In python-statemachine, an event is specified as an attribute of the state machine class declaration or directly on the Event parameter on a Transition.

Triggering events¶

Triggering an event on a state machine means invoking or sending a signal, initiating the process that may result in executing a transition.

This process usually involves

checking the current state
evaluating any guard conditions associated with the transition
executing any actions associated with the transition and (current and target) states
finally updating the current state.