Core concepts

A statechart organizes behavior around states, transitions, and events. Together they describe when the system can change, what triggers the change, and what happens as a result.

>>> from statemachine import StateChart, State

>>> class Turnstile(StateChart):
...     locked = State(initial=True)
...     unlocked = State()
...
...     coin = locked.to(unlocked, on="thank_you")
...     push = unlocked.to(locked)
...
...     def thank_you(self):
...         return "Welcome!"

>>> sm = Turnstile()
>>> sm.coin()
'Welcome!'

Even in this minimal example, the core concepts appear:

Concept	What it is	Declared as
StateChart	The container and runtime for the machine	class MyChart(StateChart)
State	A mode or condition of the system	State(), State.Compound, State.Parallel
Transition	A link from source state to target state	source.to(target), target.from_(source)
Event	A signal that triggers transitions	Class-level assignment or Event(...)
Action	A side-effect during state changes	on, before, after, enter, exit callbacks
Condition	A guard that allows/blocks a transition	cond, unless, validators parameters
Listener	An external observer of the lifecycle	listeners = [...] class attribute

Each concept below introduces the idea briefly; follow the “See also” links for the full reference. Listeners are covered in their own page.

StateChart

A StateChart is the container for states, transitions, and events. It defines the topology (which states exist and how they connect) and provides the runtime API — sending events, querying the current configuration, and managing listeners.

In the turnstile example, Turnstile is the StateChart. After instantiation, sm holds the runtime state and exposes methods like sm.send("coin"), sm.configuration, and sm.allowed_events.

See also

See StateChart for the full reference: creating instances, sending events, querying configuration, checking termination, and managing listeners at runtime.

States

A state describes what the system is doing right now. At any point in time, a statechart is “in” one or more states — the configuration. States determine which transitions are available and which events are accepted.

In the turnstile example, locked and unlocked are the two possible states. The machine starts in locked (its initial state) and can only reach unlocked when the coin event fires.

See also

See States for the full reference: initial and final states, compound (nested) states, parallel regions, history pseudo-states, and more.

Transitions

A transition is a link between a source state and a target state. When a transition fires, the system leaves the source and enters the target. Transitions can carry actions (side-effects) and conditions (guards that must be satisfied).

In the turnstile, locked.to(unlocked) is a transition: it moves the system from locked to unlocked and runs the thank_you action along the way.

See also

See Transitions for the full reference: declaring transitions, self-transitions, internal transitions, eventless (automatic) transitions, and more.

Events

An event is a signal that something has happened. Events trigger transitions — without an event, a transition will not fire (unless it is an eventless transition with a guard condition).

In the turnstile, coin and push are events. When you call sm.coin() or sm.send("coin"), the engine looks for a matching transition from the current state and fires it. Events are processed following a run-to-completion model — each event is fully handled before the next one starts.

See also

See Events for the full reference: declaring, triggering, scheduling, and naming conventions. See Processing model for how macrosteps and microsteps work under the hood.

Actions

An action is a side-effect that runs during a transition or on entry/exit of a state. Actions are how the statechart interacts with the outside world — sending notifications, updating a database, logging, or returning a value.

In the turnstile, thank_you is an action attached to the coin transition via the on parameter.

See also

See Actions for the full reference: callback naming conventions, execution order, dependency injection, and all available hooks.

Conditions

A condition (also called a guard) is a predicate that must evaluate to True for a transition to fire. A validator is similar but raises an exception to block the transition instead of silently preventing it.

Conditions let you have multiple transitions for the same event, each with a different guard — the first one that passes wins.

See also

See Conditions for the full reference: cond, unless, validators, boolean expressions, and checking enabled events.