StateMachine 3.0.0

Upgrading from 2.x? See upgrade guide for a step-by-step
migration guide.

What's new in 3.0.0

Statecharts are here! 🎉

Version 3.0 brings full statechart support to the library — compound states, parallel states,
history pseudo-states, and an SCXML-compliant processing model. It also introduces a new
StateChart base class with modern defaults, a richer event dispatch system (delayed events,
internal queues, cancellation), structured error handling, and several developer-experience
improvements.

The implementation follows the SCXML specification (W3C),
which defines a standard for statechart semantics. This ensures predictable behavior on
edge cases and compatibility with other SCXML-based tools. The automated test suite now
includes W3C-provided .scxml test cases to verify conformance.

While this is a major version with backward-incompatible changes, the existing StateMachine
class preserves 2.x defaults. See the
upgrade guide for a smooth migration path.

Compound states

Compound states have inner child states. Use State.Compound to define them
with Python class syntax — the class body becomes the state's children:

from statemachine import State, StateChart

class ShireToRoad(StateChart):
    class shire(State.Compound):
        bag_end = State(initial=True)
        green_dragon = State()
        visit_pub = bag_end.to(green_dragon)

    road = State(final=True)
    depart = shire.to(road)

sm = ShireToRoad()
set(sm.configuration_values) == {"shire", "bag_end"}
# True

sm.send("visit_pub")
"green_dragon" in sm.configuration_values
# True

sm.send("depart")
set(sm.configuration_values) == {"road"}
# True

Entering a compound activates both the parent and its initial child. Exiting removes
the parent and all descendants. See compound states for full details.

Parallel states

Parallel states activate all child regions simultaneously. Use State.Parallel:

from statemachine import State, StateChart

class WarOfTheRing(StateChart):
    class war(State.Parallel):
        class frodos_quest(State.Compound):
            shire = State(initial=True)
            mordor = State(final=True)
            journey = shire.to(mordor)
        class aragorns_path(State.Compound):
            ranger = State(initial=True)
            king = State(final=True)
            coronation = ranger.to(king)

sm = WarOfTheRing()
"shire" in sm.configuration_values and "ranger" in sm.configuration_values
# True

sm.send("journey")
"mordor" in sm.configuration_values and "ranger" in sm.configuration_values
# True

Events in one region don't affect others. See parallel states for full details.

History pseudo-states

The History pseudo-state records the configuration of a compound state when it
is exited. Re-entering via the history state restores the previously active child.
Supports both shallow (HistoryState()) and deep (HistoryState(type="deep")) history:

from statemachine import HistoryState, State, StateChart

class GollumPersonality(StateChart):
    class personality(State.Compound):
        smeagol = State(initial=True)
        gollum = State()
        h = HistoryState()
        dark_side = smeagol.to(gollum)
        light_side = gollum.to(smeagol)
    outside = State()
    leave = personality.to(outside)
    return_via_history = outside.to(personality.h)

sm = GollumPersonality()
sm.send("dark_side")
"gollum" in sm.configuration_values
# True

sm.send("leave")
sm.send("return_via_history")
"gollum" in sm.configuration_values
# True

See history states for full details on shallow vs deep history.

Eventless (automatic) transitions

Transitions without an event trigger fire automatically when their guard condition
is met:

from statemachine import State, StateChart

class BeaconChain(StateChart):
    class beacons(State.Compound):
        first = State(initial=True)
        second = State()
        last = State(final=True)
        first.to(second)
        second.to(last)
    signal_received = State(final=True)
    done_state_beacons = beacons.to(signal_received)

sm = BeaconChain()
set(sm.configuration_values) == {"signal_received"}
# True

The entire eventless chain cascades in a single macrostep. See eventless
for full details.

DoneData on final states

Final states can provide data to done.state handlers via the donedata parameter:

from statemachine import Event, State, StateChart

class QuestCompletion(StateChart):
    class quest(State.Compound):
        traveling = State(initial=True)
        completed = State(final=True, donedata="get_result")
        finish = traveling.to(completed)
        def get_result(self):
            return {"hero": "frodo", "outcome": "victory"}
    epilogue = State(final=True)
    done_state_quest = Event(quest.to(epilogue, on="capture_result"))
    def capture_result(self, hero=None, outcome=None, **kwargs):
        self.result = f"{hero}: {outcome}"

sm = QuestCompletion()
sm.send("finish")
sm.result
# 'frodo: victory'

The done_state_ naming convention automatically registers the done.state.{suffix}
form — no explicit id= needed. See done state convention for details.

Invoke

States can now spawn external work when entered and cancel it when exited, following the
SCXML <invoke> semantics (similar to UML's do/ activity). Handlers run in a daemon
thread (sync engine) or a thread executor wrapped in an asyncio Task (async engine).
Invoke is a first-class callback group — convention naming (on_invoke_<state>),
decorators (@state.invoke), inline callables, and the full SignatureAdapter dependency
injection all work out of the box.

from statemachine import State, StateChart

class FetchMachine(StateChart):
    loading = State(initial=True, invoke=lambda: {"status": "ok"})
    ready = State(final=True)
    done_invoke_loading = loading.to(ready)

sm = FetchMachine()
import time; time.sleep(0.1)  # wait for background invoke to complete
"ready" in sm.configuration_values
# True

Passing a list of callables (invoke=[a, b]) creates independent invocations — each
sends its own done.invoke event, so the first to complete triggers the transition and
cancels the rest. Use invoke_group() when you need all
callables to complete before transitioning:

from statemachine.invoke import invoke_group

class BatchFetch(StateChart):
    loading = State(initial=True, invoke=invoke_group(lambda: "a", lambda: "b"))
    ready = State(final=True)
    done_invoke_loading = loading.to(ready)

    def on_enter_ready(self, data=None, **kwargs):
        self.results = data

sm = BatchFetch()
import time; time.sleep(0.2)
sm.results
# ['a', 'b']

Invoke also supports child state machines (pass a StateChart subclass) and SCXML
<invoke> with <finalize>, autoforward, and #_<invokeid> / #_parent send targets
for parent-child communication.

See invoke for full documentation.

Event dispatch

Event matching following SCXML spec

Event matching now follows the SCXML spec — a
transition's event descriptor is a prefix match against the dot-separated event name. For
example, a transition with event="error" matches error, error.send,
error.send.failed, etc.

An event designator consisting solely of * can be used as a wildcard matching any event.

See events for full details.

Delayed events

Events can be scheduled for future processing using delay (in milliseconds). The engine
tracks execution time and processes the event only when the delay has elapsed.

sm.send("light_beacons", delay=500)  # fires after 500ms

Delayed events can be cancelled before they fire using send_id and cancel_event().
Cancellation is most useful in async codebases, where other coroutines can cancel the
event while the delay is pending. In the sync engine, the delay is blocking — the
processing loop sleeps until the delay elapses.

sm.send("light_beacons", delay=5000, send_id="beacon_signal")
sm.cancel_event("beacon_signal")  # cancel from another coroutine or callback

See delayed events for details.

raise_() — internal events

A new raise_() method sends events to the internal queue, equivalent to
send(..., internal=True). Internal events are processed immediately within the current
macrostep, before any external events. See sending events.

New send() parameters

The send() method now accepts additional optional parameters:

• delay (float): Time in milliseconds before the event is processed.
• send_id (str): Identifier for the event, useful for cancelling delayed events.
• internal (bool): If True, the event is placed in the internal queue and processed in the
  current macrostep.

Existing calls to send() are fully backward compatible.

Error handling with error.execution

When catch_errors_as_events is enabled (default in StateChart), runtime exceptions during
transitions are caught and result in an internal error.execution event. This follows
the SCXML error handling specification.

A naming convention makes this easy to use: any event attribute starting with error_
automatically matches both the underscore and dot-notation forms:

from statemachine import State, StateChart

class MyChart(StateChart):
    s1 = State("s1", initial=True)
    error_state = State("error_state", final=True)

    go = s1.to(s1, on="bad_action")
    error_execution = s1.to(error_state)  # matches "error.execution" automatically

    def bad_action(self):
        raise RuntimeError("something went wrong")

sm = MyChart()
sm.send("go")
sm.configuration == {sm.error_state}
# True

Errors are caught at the block level: each microstep phase (exit, transition on,
enter) is an independent block. An error in one block does not prevent subsequent blocks
from executing — in particular, after callbacks always run, making after_<event>() a
natural finalize hook.

The error object is available as error in handler kwargs. See error execution
for full details.

New API

configuration and configuration_values

Due to compound and parallel states, the state machine can now have multiple active states.
The new configuration property returns an OrderedSet[State] of all currently active
states, and configuration_values returns their values. These replace the deprecated
current_state property. See querying configuration.

is_terminated property

A new read-only property that returns True when the state machine has reached a final
state and the engine is no longer running. Works correctly for all topologies — flat,
compound, and parallel. See checking termination.

from statemachine import State, StateChart

class SimpleSM(StateChart):
    idle = State(initial=True)
    done = State(final=True)
    finish = idle.to(done)

sm = SimpleSM()
sm.is_terminated
# False

sm.send("finish")
sm.is_terminated
# True

In(state) condition checks

Conditions can now check if a state is in the current configuration using the
In('<state-id>') syntax. This is particularly useful in parallel regions where
a transition depends on the state of another region. See condition expressions.

from statemachine import State, StateChart

class Spaceship(StateChart):
    class systems(State.Parallel):
        class engine(State.Compound):
            off = State(initial=True)
            on = State()
            ignite = off.to(on)
        class hatch(State.Compound):
            open = State(initial=True)
            sealed = State()
            seal = open.to(sealed)
    orbit = State(final=True)
    launch = systems.to(orbit, cond="In('on') and In('sealed')")

sm = Spaceship()
sm.send("launch")  # engine off, hatch open — guard fails
"off" in sm.configuration_values
# True

sm.send("ignite")
sm.send("launch")  # engine on, hatch still open — guard fails
"on" in sm.configuration_values and "open" in sm.configuration_values
# True

sm.send("seal")
sm.send("launch")  # both conditions met — launches!
sm.is_terminated
# True

prepare_event() callback

The prepare_event callback lets you inject custom data into **kwargs for all
other callbacks in the same event processing cycle. See preparing events.

from statemachine import State, StateMachine

class ExampleStateMachine(StateMachine):
    initial = State(initial=True)

    loop = initial.to.itself()

    def prepare_event(self):
        return {"foo": "bar"}

    def on_loop(self, foo):
        return f"On loop: {foo}"

sm = ExampleStateMachine()

sm.loop()
# 'On loop: bar'

Constructor kwargs forwarded to initial state callbacks

Constructor keyword arguments are forwarded to initial state callbacks, so self-contained
machines can receive context at creation time:

from statemachine import State, StateChart

class Greeter(StateChart):
    idle = State(initial=True)
    done = State(final=True)
    idle.to(done)

    def on_enter_idle(self, name=None, **kwargs):
        self.greeting = f"Hello, {name}!"

sm = Greeter(name="Alice")
sm.greeting
# 'Hello, Alice!'

Developer experience

StateChart base class

The new StateChart class is the recommended base for all new state machines. It enables
SCXML-compliant defaults: catch_errors_as_events, enable_self_transition_entries, and
non-atomic configuration updates. The existing StateMachine class is now a subclass with
backward-compatible defaults. See behaviour for a comparison table.

Typed models with Generic[TModel]

StateChart now supports a generic type parameter for the model, enabling full type
inference and IDE autocompletion on sm.model:

from statemachine import State, StateChart

class MyModel:
    name: str = ""
    value: int = 0

class MySM(StateChart["MyModel"]):
    idle = State(initial=True)
    active = State(final=True)
    go = idle.to(active)

sm = MySM(model=MyModel())
sm.model.name
# ''

With this declaration, type checkers infer sm.model as MyModel (not Any), so
accessing sm.model.name or sm.model.value gets full autocompletion and type safety.
When no type parameter is given, StateChart defaults to StateChart[Any] for backward
compatibility. See domain models for details.

Improved type checking with pyright

The library now supports pyright in addition to mypy.
Type annotations have been improved throughout the codebase, and a catch-all __getattr__
that previously returned Any has been removed — type checkers can now detect misspelled
attribute names and unresolved references on StateChart subclasses.

Self-transition entry/exit behavior

In StateChart, self-transitions now execute entry and exit actions, following the SCXML
spec. The enable_self_transition_entries class attribute controls this behavior.
StateMachine preserves the 2.x default (no entry/exit on self-transitions).
See self transition.

Class-level listener declarations

Listeners can now be declared at the class level using the listeners attribute, so they are
automatically attached to every instance. The list accepts callables (classes, partial, lambdas)
as factories that create a fresh listener per instance, or pre-built instances that are shared.

A setup() protocol allows factory-created listeners to receive runtime dependencies
(DB sessions, Redis clients, etc.) via **kwargs forwarded from the SM constructor.

Inheritance is supported: child listeners are appended after parent listeners, unless
listeners_inherit = False is set to replace them entirely.

See observers for full documentation.

Weighted (probabilistic) transitions

A new contrib module statemachine.contrib.weighted provides weighted_transitions(),
enabling probabilistic transition selection based on relative weights. This works entirely
through the existing condition system — no engine changes required.

See weighted transitions for full documentation.

State timeouts

A new contrib module statemachine.contrib.timeout provides a timeout() invoke helper
for per-state watchdog timers. When a state is entered, a background timer starts; if the
state is not exited before the timer expires, an event is sent automatically. The timer is
cancelled on state exit, with no manual cleanup needed.

from statemachine import State, StateChart
from statemachine.contrib.timeout import timeout

class WaitingMachine(StateChart):
    waiting = State(initial=True, invoke=timeout(5, on="expired"))
    timed_out = State(final=True)
    expired = waiting.to(timed_out)

sm = WaitingMachine()
sm.waiting.is_active
# True

See timeout for full documentation.

Create state machine from a dict definition

Dynamically create state machine classes using
create_machine_class_from_definition():

from statemachine.io import create_machine_class_from_definition

machine = create_machine_class_from_definition(
    "TrafficLightMachine",
    **{
        "states": {
            "green": {"initial": True, "on": {"change": [{"target": "yellow"}]}},
            "yellow": {"on": {"change": [{"target": "red"}]}},
            "red": {"on": {"change": [{"target": "green"}]}},
        },
    }
)

sm = machine()
sm.green.is_active
# True
sm.send("change")
sm.yellow.is_active
# True

Async concurrent event result routing

When multiple coroutines send events concurrently via asyncio.gather, each
caller now receives its own event's result (or exception). Previously, only the
first caller to acquire the processing lock would get a result — subsequent
callers received None and exceptions could leak to the wrong caller.

This is implemented by attaching an asyncio.Future to each externally
enqueued event in the async engine. See async for details.

Fixes #509.

Migration guide from pytransitions

A new Coming from pytransitions guide helps users of the
transitions library evaluate the differences
and migrate their state machines. It includes side-by-side code comparisons and a feature matrix.

Migration guide from the GoF State Pattern

A new Coming from the State Pattern guide helps developers
familiar with the classic Gang of Four State Pattern understand how to port their hand-rolled
state implementations to python-statemachine. It walks through a complete example, compares
the two approaches, and highlights what you gain from the declarative style.

Validation flags

The strict_states class parameter has been replaced by two independent, always-on
class-level attributes:

• validate_trap_states: non-final states must have at least one outgoing transition.
• validate_final_reachability: when final states exist, all non-final states must have
  a path to at least one final state.
• validate_disconnected_states: all states must be reachable from the initial state.

See validations for details.

Known limitations

The following SCXML features are not yet implemented and are deferred to a future release:

• HTTP and other external communication targets (only #_internal, #_parent, and
  #_<invokeid> send targets are supported)

For a step-by-step migration guide with before/after examples, see
Upgrading from 2.x to 3.0.

Backward incompatible changes in 3.0

This section summarizes the breaking changes. For detailed before/after examples and
migration instructions, see the upgrade guide.

• Python 3.7 and 3.8 dropped. StateMachine 3.0 supports Python 3.9 through 3.14.
• Non-RTC model removed. The rtc parameter (deprecated since 2.3.2) has been removed.
  All events are now queued before being processed.
• current_state deprecated. Use configuration / configuration_values instead.
  With compound and parallel states, multiple states can be active simultaneously.
• Configuration update timing. In StateChart, states are exited before on callbacks
  and entered after, following the SCXML spec. Two new kwargs — previous_configuration and
  new_configuration — are available in on callbacks. Use atomic_configuration_update=True
  or the StateMachine class to restore the 2.x behavior.
• Self-transition entry/exit. In StateChart, self-transitions now trigger on_enter_* /
  on_exit_* callbacks. Set enable_self_transition_entries = False to restore the old behavior.
• add_observer() removed. Use add_listener() instead.
• TransitionNotAllowed changes. Now stores configuration (a set) instead of state,
  and event can be None.
• allow_event_without_transition moved to class level. No longer an __init__ parameter.
• States.from_enum default changed. use_enum_instance now defaults to True.
• Short registry names removed. Use fully-qualified names with get_machine_cls().
• strict_states removed. Replaced by validate_trap_states and
  validate_final_reachability (both default to True).
• __repr__ output changed. Now shows configuration=[...] instead of current_state=....