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)[source]¶

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.

exception TransitionNotAllowed(event, state)¶: Raised when there’s no transition that can run from the current State.

add_observer(*observers)[source]¶

Add an observer.

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

See also

Observers.

property allowed_events¶: List of the current allowed events.

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 = []¶

name = 'StateMachine'¶

send(event, *args, **kwargs)[source]¶: Send an Event to the state machine.

See also

See: Triggering events.

states: List[State] = []¶: List of all state machine States.

states_map: Dict[Any, State] = {}¶: Map of state.value to the corresponding State.

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)[source]¶

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')]

property from_¶: Create transitions from the given target states (reversed).

property to¶: Create transitions to the given target states.

Transition¶

See also

Transitions reference.

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

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=None)[source]¶

Model¶

See also

Domain models reference.

class statemachine.model.Model[source]¶

TriggerData¶

class statemachine.event_data.TriggerData(machine: 'StateMachine', event: str, args: tuple = <factory>, kwargs: dict = <factory>)[source]¶

args: tuple¶: All positional arguments provided on the Event.

event: str¶: 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.

EventData¶

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

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: statemachine.event_data.TriggerData¶: The TriggerData of the Event.