feat: StateChart (support for compound / parallel / historical states including SCXML notation)

[fgmacedo]

Statecharts are here

This PR brings full statechart support to python-statemachine — the most significant evolution of the library since its creation. What started as an exploration of nested states grew into a comprehensive implementation of the SCXML specification (W3C), introducing compound states, parallel states, history pseudo-states, eventless transitions, error handling, and much more.

This is a major version release (3.0.0) with backwards-incompatible changes. The StateMachine class is preserved for backwards compatibility, while the new StateChart class provides full SCXML-compliant behavior out of the box.

Compound states

States can now contain inner substates using State.Compound with Python class syntax:

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)

Entering a compound state activates both the parent and its initial child. Exiting removes the parent and all descendants.

Parallel states

Multiple regions can be active simultaneously using State.Parallel:

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)

Events in one region don't affect others — true orthogonal concurrency.

History pseudo-states

The HistoryState records the configuration of a compound state when exited. Re-entering via history restores the previously active child (shallow or deep):

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

Eventless (automatic) transitions

Transitions without an event trigger fire automatically when their source state is active, cascading through the entire chain in a single macrostep.

DoneData on final states

Final states can provide data to done.state handlers via the donedata parameter, following the SCXML spec for communicating completion results.

Error handling with error.execution

When error_on_execution is enabled (default in StateChart), runtime exceptions are caught and result in an internal error.execution event — following the SCXML error handling specification. A error_ naming convention makes it easy:

class MyChart(StateChart):
    s1 = State(initial=True)
    error_state = State(final=True)
    go = s1.to(s1, on="bad_action")
    error_execution = s1.to(error_state)  # matches "error.execution" automatically

Additional features

• Delayed events — sm.send("event", delay=500) with cancellation via sm.cancel_event(send_id)
• Event matching per SCXML spec — hierarchical event name matching with wildcard * support
• In(state) condition checks — cond="In('state_id')" to check active configuration
• prepare_event callback — inject custom kwargs into all callbacks
• Multi-target transitions — a single transition can target multiple states
• Dictionary-based definitions — create_machine_class_from_definition() for dynamic state machine creation
• Diagram generation — Graphviz rendering for compound, parallel, and history states with proper subgraph nesting

Engine architecture

Both the sync and async engines have been rewritten to implement the SCXML processing model:

• 3-phase macrostep loop (eventless → internal queue → external queue)
• Proper enter/exit ordering following the SCXML algorithm
• configuration (ordered set of active states) replaces current_state
• Internal and external event queues with priority handling

SCXML compliance

The test suite includes 198 W3C SCXML test cases (mandatory + optional), run on both sync and async engines. Currently 152 pass and 46 are marked as expected failures (mostly requiring <invoke> which is deferred to v3.1+).

Quality

• 100% test coverage — 988 tests, 0 missing lines, 0 missing branches
• Full support for both sync and async engines across all features
• SonarCloud issues addressed
• Comprehensive documentation with doctests

Backwards compatibility

The StateMachine class preserves the old behavior through class-level attribute defaults:

Attribute	StateChart	StateMachine
allow_event_without_transition	True	False
enable_self_transition_entries	True	False
atomic_configuration_update	False	True
error_on_execution	True	False

Existing StateMachine subclasses continue to work as before.

Known limitations (deferred to v3.1+)

• <invoke> — invoking external services or sub-machines
• HTTP and other external communication targets
• <finalize> — processing data returned from invoked services

---

Closes #439, #455. Supersedes #329.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (d062de9) to head (76b2a85).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff              @@
##           develop      #501      +/-   ##
============================================
+ Coverage    99.77%   100.00%   +0.22%     
============================================
  Files           25        31       +6     
  Lines         1756      3592    +1836     
  Branches       230       553     +323     
============================================
+ Hits          1752      3592    +1840     
+ Misses           2         0       -2     
+ Partials         2         0       -2     

Flag	Coverage Δ
unittests	100.00% <100.00%> (+0.22%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[comalice]

Is this in a state (🤣) that I could try it out? I have several use-cases where the sub-state functionality would be useful and I'd be glad to give feedback if I run into issues.

Note, the user experience I had expected looked something like this:

class SubMachine(StateMachine):
    test = State(initial=True)
    test_complete = State(final=True)

    next = test.to(test_complete)


class TestSM(StateMachine):
    initial_state = State(initial=True)
    sub_machine_as_state = SubMachine()
    some_other_state = State(final=True)

    goto_sub_machine = initial_state.to(sub_machine_as_state)
    goto_finish = sub_machine_as_state.to(some_other_state)

And then something like

sm = TestSM()

sm.send('goto_sub_machine')
sm.send('next')   # TestSM now has the submachine states as states it can traverse.
sm.send('goto_finish')

[sonarqubecloud]

Quality Gate passed

Issues
16 New issues
5 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.9% Duplication on New Code

See analysis details on SonarQube Cloud