API

StateMachine

class statemachine.statemachine.StateMachine(model: Any = None, state_field: str = 'state', start_value: Any = None, rtc: bool = True, allow_event_without_transition: bool = False, listeners: List[object] | None = None)

Parameters:

• model – An optional external object to store state. See Domain models.

• state_field (str) – The model’s field which stores the current state. Default: state.

• start_value – An optional start state value if there’s no current state assigned on the Domain models. Default: None.

• rtc (bool) – Controls the Processing model. Defaults to True that corresponds to a run-to-completion (RTC) model.

• allow_event_without_transition – If False when an event does not result in a transition, an exception TransitionNotAllowed will be raised. If True the state machine allows triggering events that may not lead to a state Transition, including tolerance to unknown Event triggers. Default: False.

• listeners – An optional list of objects that provies attributes to be used as callbacks. See Listeners for more details.

exception TransitionNotAllowed(event: Event, state: State)

Shortcut for easy exception handling.

Example:

try:
    sm.send("an-inexistent-event")
except sm.TransitionNotAllowed:
    pass

activate_initial_state()

add_listener(*listeners)

Add a listener.

Listener are a way to generically add behavior to a StateMachine without changing its internal implementation.

See also

Listeners.

add_observer(*observers)

Add a listener.

property allowed_events: List[Event]

List of the current allowed events.

bind_events_to(*targets)

Bind the state machine events to the target objects.

property current_state: State

Get/Set the current State.

This is a low level API, that can be to assign any valid state completely bypassing all the hooks and validations.

property current_state_value

Get/Set the current State value.

This is a low level API, that can be used to assign any valid state value completely bypassing all the hooks and validations.

events = []

final_states = []

initial_state = None

name = 'StateMachine'

send(event: str, *args, **kwargs)

Send an Event to the state machine.

See also

See: Triggering events.

states = []

states_map = {}

State

See also

States reference.

class statemachine.state.State(name: str = '', value: Any = None, initial: bool = False, final: bool = False, enter: Any = None, exit: Any = None)

A State in a StateMachine describes a particular behavior of the machine. When we say that a machine is “in” a state, it means that the machine behaves in the way that state describes.

Parameters:

• name –

  A human-readable representation of the state. Default is derived from the name of the variable assigned to the state machine class. The name is derived from the id using this logic:

  name = id.replace("_", " ").capitalize()
  

• value – A specific value to the storage and retrieval of states. If specified, you can use It to map a more friendly representation to a low-level value.

• initial – Set True if the State is the initial one. There must be one and only one initial state in a statemachine. Defaults to False.

• final – Set True if represents a final state. A machine can have optionally many final states. Final states have no Transition starting from It. Defaults to False.

• enter – One or more callbacks assigned to be executed when the state is entered. See Actions.

• exit – One or more callbacks assigned to be executed when the state is exited. See Actions.

State is a core component on how this library implements an expressive API to declare StateMachines.

>>> from statemachine import State

Given a few states…

>>> draft = State("Draft", initial=True)

>>> producing = State("Producing")

>>> closed = State('Closed', final=True)

Transitions are declared using the State.to() or State.from_() (reversed) methods.

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

The result is a TransitionList. Don’t worry about this internal class. But the good thing is that it implements the OR operator to combine transitions, so you can use the | syntax to compound a list of transitions and assign to the same event.

You can declare all transitions for a state in one single line …

>>> transitions = draft.to(draft) | producing.to(closed)

… and you can append additional transitions for a state to previous definitions.

>>> transitions |= closed.to(draft)

>>> [(t.source.name, t.target.name) for t in transitions]
[('Draft', 'Draft'), ('Producing', 'Closed'), ('Closed', 'Draft')]

There are handy shortcuts that you can use to express this same set of transitions.

The first one, draft.to(draft), is also called a Self transition, and can be expressed using an alternative syntax:

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

You can even pass a list of target states to declare at once all transitions starting from the same state.

>>> transitions = draft.to(draft, producing, closed)

>>> [(t.source.name, t.target.name) for t in transitions]
[('Draft', 'Draft'), ('Draft', 'Producing'), ('Draft', 'Closed')]

Sometimes it’s easier to use the State.from_() method:

>>> transitions = closed.from_(draft, producing, closed)

>>> [(t.source.name, t.target.name) for t in transitions]
[('Draft', 'Closed'), ('Producing', 'Closed'), ('Closed', 'Closed')]

property from_: _FromState

Create transitions from the given target states (reversed).

property to: _ToState

Create transitions to the given target states.

States (class)

class statemachine.states.States(states: Dict[str, State] | None = None)

A class representing a collection of State objects.

Helps creating StateMachine’s State definitions from other sources, like an Enum class, using States.from_enum().

>>> states_def = [('open', {'initial': True}), ('closed', {'final': True})]

>>> from statemachine import StateMachine
>>> class SM(StateMachine):
...
...     states = States({
...         name: State(**params) for name, params in states_def
...     })
...
...     close = states.open.to(states.closed)

And states can be used as usual.

>>> sm = SM()
>>> sm.send("close")
>>> sm.current_state.id
'closed'

__init__(states: Dict[str, State] | None = None) → None

Initializes a new instance of the States class.

Parameters:

states – A dictionary mapping keys as State.id and values State instances.

Returns:

None.

classmethod from_enum(enum_type: Type[Enum], initial, final=None, use_enum_instance: bool = False)

Creates a new instance of the States class from an enumeration.

Consider an Enum type that declares our expected states:

>>> class Status(Enum):
...     pending = 1
...     completed = 2

A StateMachine that uses this enum can be declared as follows:

>>> from statemachine import StateMachine
>>> class ApprovalMachine(StateMachine):
...
...     _ = States.from_enum(Status, initial=Status.pending, final=Status.completed)
...
...     finish = _.pending.to(_.completed)
...
...     def on_enter_completed(self):
...         print("Completed!")

Tip

When you assign the result of States.from_enum to a class-level variable in your StateMachine, you’re all set. You can use any name for this variable. In this example, we used _ to show that the name doesn’t matter. The metaclass will inspect the variable of type States (class) and automatically assign the inner State instances to the state machine.

Everything else is similar, the Enum is only used to declare the State instances.

>>> sm = ApprovalMachine()

>>> sm.pending.is_active
True

>>> sm.send("finish")
Completed!

>>> sm.completed.is_active
True

>>> sm.current_state_value
2

If you need to use the enum instance as the state value, you can set the use_enum_instance=True:

>>> states = States.from_enum(Status, initial=Status.pending, use_enum_instance=True)
>>> states.completed.value
<Status.completed: 2>

Deprecated since version 2.3.3: On the next major release, use_enum_instance=True will be the default.

Parameters:

• enum_type – An enumeration containing the states of the machine.

• initial – The initial state of the machine.

• final – A set of final states of the machine.

• use_enum_instance – If True, the value of the state will be the enum item instance, otherwise the enum item value. Defaults to False.

Returns:

A new instance of the States (class).

items()

Returns a view object of the states, with pairs of (State.id, State).

Parameters:

None.

Returns:

A view object of the items in the the instance.

Transition

See also

Transitions reference.

class statemachine.transition.Transition(source: State, target: State, event=None, internal=False, validators=None, cond=None, unless=None, on=None, before=None, after=None)

A transition holds reference to the source and target state.

Parameters:

• source (State) – The origin state of the transition.

• target (State) – The target state of the transition.

• event (Optional[Union[str, List[str]]]) – List of designators of events that trigger this transition. Can be either a list of strings, or a space-separated string list of event descriptors.

• internal (bool) – Is the transition internal or external? Internal transitions don’t execute the state entry/exit actions. Default False.

• validators (Optional[Union[str, Callable, List[Callable]]]) – The validation callbacks to be invoked before the transition is executed.

• cond (Optional[Union[str, Callable, List[Callable]]]) – The condition callbacks to be invoked before the transition is executed that should evaluate to True.

• unless (Optional[Union[str, Callable, List[Callable]]]) – The condition callbacks to be invoked if the cond is False before the transition is executed.

• on (Optional[Union[str, Callable, List[Callable]]]) – The callbacks to be invoked when the transition is executed.

• before (Optional[Union[str, Callable, List[Callable]]]) – The callbacks to be invoked before the transition is executed.

• after (Optional[Union[str, Callable, List[Callable]]]) – The callbacks to be invoked after the transition is executed.

TransitionList

class statemachine.transition_list.TransitionList(transitions: Iterable[Transition] | None = None)

A list-like container of Transitions with callback functions.

__getitem__(index: int) → Transition

Returns the Transition at the specified index.

Parameters:

index – The index of the transition.

Returns:

The Transition at the specified index.

__init__(transitions: Iterable[Transition] | None = None)

Parameters:

transitions – An iterable of Transition objects. Defaults to None.

__len__()

Returns the number of transitions in the TransitionList instance.

Returns:

The number of transitions.

__or__(other: TransitionList | Iterable)

Return a new TransitionList that combines the transitions of this TransitionList with another TransitionList or iterable.

Parameters:

other – Another TransitionList or iterable of Transition objects.

Returns:

A new TransitionList object that combines the

transitions of this TransitionList with other.

Return type:

TransitionList

__repr__()

Return a string representation of the TransitionList.

add_event(event: str)

Adds an event to all transitions in the TransitionList instance.

Parameters:

event – The name of the event to be added.

add_transitions(transition: Transition | TransitionList | Iterable)

Adds one or more transitions to the TransitionList instance.

Parameters:

transition – A sequence of transitions or a TransitionList instance.

Returns:

The updated TransitionList instance.

property unique_events: List[Event]

Returns a list of unique event names across all transitions in the TransitionList instance.

Returns:

A list of unique event names.

Model

See also

Domain models reference.

class statemachine.model.Model

state

Holds the current State value of the StateMachine.

TriggerData

class statemachine.event_data.TriggerData(machine: 'StateMachine', event: 'Event', args: tuple = <factory>, kwargs: dict = <factory>)

args: tuple

All positional arguments provided on the Event.

event: Event

The Event that was triggered.

kwargs: dict

All keyword arguments provided on the Event.

model: Any

A reference to the underlying model that holds the current State.

Event

class statemachine.event.Event(transitions: str | TransitionList | None = None, id: str | None = None, name: str | None = None, _sm: StateMachine | None = None)

An event triggers a signal that something has happened.

They are sent 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.

See also Events.

__call__(*args, **kwargs)

Send this event to the current state machine.

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

id: str

The event identifier.

name: str

The event name.

EventData

class statemachine.event_data.EventData(trigger_data: statemachine.event_data.TriggerData, transition: 'Transition', result: 'Any | None' = None, executed: bool = False)

source: State

The State which StateMachine was in when the Event started.

state: State

The current State of the StateMachine.

target: State

The destination State of the Transition.

transition: Transition

The Transition instance that was activated by the Event.

trigger_data: TriggerData

The TriggerData of the Event.