Highlights

• Load statecharts from documents. A single, secure statemachine.io.load
  reads SCXML, JSON and YAML into a running StateChart. From an inline definition:

  from statemachine.io import load
  
  Light = load(
      """
      states:
        green: {initial: true, on: {next: [{target: red}]}}
        red: {on: {next: [{target: green}]}}
      """,
      format="yaml",
  )
  sm = Light()
  sm.send("next")

  Or from a file, with the format detected from the extension:

  Machine = load("traffic_light.scxml")

• Safe by default. Expressions in loaded documents are evaluated by a restricted
  allowlist, never eval — this also closes a code-execution vulnerability in the old
  SCXML loader (CVE-2026-47103); see Security below.

• Python 3.10+ now required. Support for the end-of-life Python 3.9 was dropped.

Security: arbitrary code execution when loading SCXML (CVE-2026-47103)

In short: before 3.2.0, loading an SCXML document with SCXMLProcessor evaluated the
expressions inside it with Python's eval/exec, so a .scxml file from an untrusted
source could run arbitrary code on your machine. 3.2.0 makes loading safe by default:
expressions are evaluated by a restricted allowlist and <script> is rejected.

What changed. Guards and datamodel expressions (cond, <assign>, <send>,
<foreach>, <log>, …) are now compiled by a restricted AST allowlist — arithmetic,
comparisons, collections, indexing, attribute reads and the In(...) predicate, but no
builtins, dunder access, or function/method calls. <script> is rejected. This mirrors
yaml.safe_load vs yaml.load.

Trusting a document. For SCXML you author yourself (hand-written documents or the W3C
conformance suite), opt back into full Python with trusted=True:

from statemachine.io.scxml.processor import SCXMLProcessor

SCXMLProcessor()              # safe default: restricted evaluator, <script> rejected
SCXMLProcessor(trusted=True)  # full eval/exec — only for documents you trust

A restricted-mode document that uses an unsupported construct fails to load with
InvalidDefinition; runtime evaluation errors still surface as error.execution events.

Refs: GHSA-v4jc-pm6r-3vj8, CVE-2026-47103, CWE-95.

What's new in 3.2.0

First-class statechart IO: load from SCXML, JSON and YAML

Statecharts can now be loaded from declarative documents through a single, secure
facade, statemachine.io.load:

from statemachine.io import load

Machine = load("traffic_light.yaml")   # format detected from the extension
sm = Machine()

• Three formats behind one API: SCXML (.scxml/.xml), JSON (.json) and YAML
  (.yaml/.yml). The format is detected from the file extension or set explicitly with
  format=.
• Secure by default. Guards and datamodel expressions are evaluated by a restricted
  AST-allowlist evaluator; <script> / arbitrary Python is rejected unless you pass
  trusted=True. YAML is always parsed with safe-load semantics.
• Functional parity across formats. The native floor is the SCXML ceiling: everything
  SCXML expresses is expressible in JSON/YAML and behaves the same. cond/unless are
  real expressions (count >= 3, boolean algebra, In(state)); there is a structured
  action vocabulary (assign/raise/log/if/foreach/send/cancel); the system
  variables (_event/_sessionid/_name/_ioprocessors) are available in every format;
  and invoke works natively (invoke: [{src|content, id, params, namelist, finalize}]).
  All of this works under trusted=False.
• Publishable, validatable schema. The native JSON/YAML format has a published
  JSON Schema
  (Draft 2020-12); pass validate=True (with the [validation] extra) to validate on
  load.
• Low-level access via statemachine.io.build_processor for documents that
  declare or invoke several machines.

See the IO and formats guide for the full guide.

Architecture: a format-neutral runtime

The IO stack is a ports-and-adapters design. SCXML defines the execution model and
behavior; the XML syntax is just one format. So the runtime is the format-neutral
Interpreter (statemachine.io.interpreter), parameterized by a reader (the format
port) and an evaluator (secure by default), composing a DefinitionBuilder
(statemachine.io.builder) that compiles the neutral IR (statemachine.io.model) into a
StateChart class. The class registry (for invoke), sessions and the system variables live
in this neutral runtime. SCXMLProcessor is now a thin Interpreter preconfigured with
the SCXML reader; its parse_scxml API is preserved (use io.load for files).

New optional dependencies

python-statemachine[yaml]        # PyYAML, for the YAML format
python-statemachine[validation]  # jsonschema, for validate=True
python-statemachine[io]          # both of the above

Backward incompatible changes in 3.2.0

Python 3.9 support dropped

Python 3.9 reached end-of-life on 2025-10-31 and is no longer supported by
the Python core team. StateMachine 3.2 now requires Python 3.10+.

Rationale:

• Python 3.9 represented around 1.4% of PyPI downloads of
  python-statemachine in the 180 days prior to this release;
  Python 3.10+ accounts for the vast majority of attributable traffic.
• Dropping 3.9 lets the codebase adopt match/case (PEP 634), PEP 604
  union syntax (X | Y), PEP 585 built-in generics (list[int] instead
  of List[int]), and zip(strict=True) (PEP 618) internally.
• The same minimum has already been adopted by the major libraries in
  the ecosystem (pandas, FastAPI, SQLAlchemy, NumPy, Django 5).

Migration

• Upgrade your interpreter to Python 3.10 or later, or
• Pin python-statemachine<3.2 to stay on the 3.1.x line.

No public API was changed by this drop. Code that runs on 3.10+ today
will continue to run unchanged on 3.2.

statemachine.io.scxml internals reorganized

The experimental statemachine.io.scxml internals were promoted into a format-neutral
IO core (see What's new above). Code that imported implementation modules directly must
update its imports:

statemachine.io.scxml.processor.SCXMLProcessor (now a thin wrapper over the new
format-neutral runtime, minus the removed parse_scxml_file; use io.load for files) and
statemachine.io.create_machine_class_from_definition keep their behavior. The runtime
itself moved into the new, SCXML-agnostic statemachine.io.interpreter.Interpreter and
statemachine.io.builder (see Architecture above).

Bug fixes in 3.2.0

Sibling compound states with same-named children no longer collide

A StateChart with sibling compound states whose children reuse the same local
id (e.g. each region declares an a and a b) but carry distinct value=
identifiers would collapse in the internal instance-state map, which was keyed by
state.id. The duplicate ids overwrote each other, so dispatching an event
resolved to the wrong State instance and raised TransitionNotAllowed.

Instance states are now keyed by state.value (globally unique, the canonical
identifier already used by states_map), fixing dispatch for nested and parallel
configurations that repeat child names.

#624,
#625.

Async invoke no longer cancels itself on its own done.invoke

When an async invoke completed and its done.invoke event triggered a
transition out of the owning state, the cancel-on-exit path could cancel the
invocation's own task while it was still running. The CancelledError surfaced at
the next await, so the target state's on_enter callback never finished.

The engine now skips self-cancellation when the invocation's task is the currently
running task, letting the originating handler complete normally.

#627.

validators in a dict/JSON transition definition are no longer dropped

create_machine_class_from_definition (the dict/JSON adapter behind
statemachine.io.load) threaded cond, unless, on, before and
after from each transition definition into the Transition, but not
validators. A validators entry was silently ignored, so it never ran at
send(), leaving dict/JSON-defined machines without the explicit-rejection
channel (raise to abort with a reason) that validators provides. The
TransitionDict type also mistyped validators as bool.

validators is now materialized onto the Transition like the other callback
specs, and the type was corrected to the same callback-spec union as
cond/unless.

#628,
#629.

Bug fixes in 3.1.2

pydot is optional again

Starting in 3.1.0, defining any StateMachine or StateChart subclass
implicitly required pydot to be installed. The metaclass invokes
_expand_docstring() for every class, and that path eagerly imported the
diagram formatter, which in turn imported pydot at module load time, so
import of a user module failed with ModuleNotFoundError: No module named 'pydot' even when no diagrams were rendered.

Two changes restore the original behavior:

• _expand_docstring now short-circuits when the class docstring contains
  no {statechart:FORMAT} placeholder, skipping the formatter import for
  the common case.
• statemachine.contrib.diagram no longer re-exports renderer classes at
  the package top level, and renderer modules are only imported when
  actually used. The dependency is only resolved when dot/svg
  rendering is requested. Mermaid and Markdown/RST formats work without
  pydot.

If your code imports DotRenderer, DotRendererConfig, MermaidRenderer
or MermaidRendererConfig directly from statemachine.contrib.diagram,
import them from the renderer submodule instead:

from statemachine.contrib.diagram.renderers.dot import DotRenderer
from statemachine.contrib.diagram.renderers.mermaid import MermaidRenderer

#622.

Other changes in 3.1.2

Security and dependency bumps

Picked up from the dependency refresh applied to main:

• ruff >=0.15.13
• pytest >=9.0.3 (CVE-2025, tmpdir handling) for py>=3.10
• django >=5.2.14 for py3.10/3.11 (multiple CVEs)
• pillow >=12.2.0 for py>=3.10 (multiple CVEs)
• transitive: urllib3 2.6.3 -> 2.7.0 (GHSA-qccp-gfcp-xxvc), requests
  2.33.1 -> 2.34.2

CI workflows: actions/checkout v4 → v5, actions/setup-python v5 → v6,
astral-sh/setup-uv v3 → v8 (pinned to v8.1.0), codecov/codecov-action
v4 → v6.

StateChart 3.1.1

May 15, 2026

Bug fixes in 3.1.1

Thread-safety hardening of the configuration cache

Two races in Configuration (introduced indirectly by the cache + no-copy
design in 3.1.0) have been fixed. Both surfaced under concurrent reads of
machine.configuration while another thread is sending events to the same
state machine instance, a scenario explicitly supported by the sync engine.

1. Cache read race. Configuration.states checked
   self._cached is not None and then returned self._cached. Another
   thread invalidating between the check and the return could cause the
   property to return None, leading to a TypeError in callers that
   iterate the result (e.g., list(machine.configuration)). The getter now
   snapshots the cache fields locally before the freshness check.
   #620.

2. In-place mutation race. Configuration.add() and
   Configuration.discard() mutated the OrderedSet stored on the model
   in place and rewrote the same reference. A concurrent reader iterating
   .configuration could observe a partially mutated set (raising
   RuntimeError: Set changed size during iteration) or read back a stale
   cached resolution missing the new state. Both methods now use
   copy-on-write, producing a fresh OrderedSet per call. This affects
   only StateChart (where atomic_configuration_update=False is the
   default to support parallel regions). The atomic update path used by
   StateMachine was never affected.
   #620.

Both fixes are covered by new stress tests in
tests/test_threading.py::TestThreadSafety:
test_concurrent_send_and_read_configuration and
test_concurrent_parallel_region_send_and_read, plus a deterministic
copy-on-write contract test test_add_discard_produce_fresh_orderedset.

Performance impact

Copy-on-write in add() / discard() reintroduces an O(n) shallow copy of
the active configuration on every state entry and exit. For the typical
configuration sizes used in practice (1–7 states), this is sub-microsecond.

Measured on macOS / Python 3.14, pytest-benchmark median, vs 3.1.0:

Overall 4.7x–7.7x event throughput improvement vs 3.0.0 (declared in
3.1.0 release notes)
is unchanged.

StateChart 3.1.0

May 15, 2026

📘 Full docs: https://python-statemachine.readthedocs.io/en/v3.1.0/

What's new in 3.1.0

Text representations with format()

State machines now support Python's built-in format() protocol. Use f-strings
or format() to get text representations — on both classes and instances:

f"{TrafficLightMachine:md}"
f"{sm:mermaid}"
format(sm, "rst")

Supported formats:

See Text representations for details.

Formatter facade

A new Formatter facade with decorator-based registration unifies all text
format rendering behind a single API. Adding a new format requires only
registering a render function — no changes to __format__, the CLI, or the
Sphinx directive:

from statemachine.contrib.diagram import formatter

formatter.render(sm, "mermaid")
formatter.supported_formats()

@formatter.register_format("custom")
def _render_custom(machine_or_class):
    ...

See Using the formatter API for details.

Mermaid diagram support

State machines can now be rendered as
Mermaid stateDiagram-v2
source text — no Graphviz installation required. Supports compound states,
parallel regions, history states, guards, and active-state highlighting.

Three ways to use it:

• f-strings: f"{sm:mermaid}"
• CLI: python -m statemachine.contrib.diagram MyMachine - --format mermaid
• Sphinx directive: :format: mermaid renders via sphinxcontrib-mermaid.

See Mermaid format for details.

Auto-expanding docstrings

Use {statechart:FORMAT} placeholders in your class docstring to embed a
live representation of the state machine. The placeholder is replaced at
class definition time, so the docstring always stays in sync with the code:

class TrafficLight(StateChart):
    """A traffic light.

    {statechart:md}
    """
    green = State(initial=True)
    yellow = State()
    red = State()
    cycle = green.to(yellow) | yellow.to(red) | red.to(green)

Any registered format works: md, rst, mermaid, dot, etc.
Works with Sphinx autodoc — the expanded docstring is what gets rendered.
See Auto-expanding docstrings for details.

Sphinx directive for inline diagrams

A new Sphinx extension renders state machine diagrams directly in your
documentation from an importable class path — no manual image generation
needed.

Add "statemachine.contrib.diagram.sphinx_ext" to your conf.py
extensions, then use the directive in any MyST Markdown page:

```{statemachine-diagram} myproject.machines.OrderControl
:events: receive_payment
:caption: After payment
:target:
```

The directive supports the same options as the standard image/figure
directives (:width:, :height:, :scale:, :align:, :target:,
:class:, :name:), plus :events: to instantiate the machine and send
events before rendering (highlighting the current state).

Using :target: without a value makes the diagram clickable, opening the
full SVG in a new browser tab for zooming — useful for large statecharts.

The :format: mermaid option renders via sphinxcontrib-mermaid instead of
Graphviz.

See Sphinx directive for full documentation.
#589.

Diagram CLI --events and --format options

The python -m statemachine.contrib.diagram command now accepts:

• --events to instantiate the machine and send events before rendering,
  highlighting the current active state.
• --format to choose the output format (mermaid, md, rst, dot, svg,
  or image formats via Graphviz). Use - as the output path to write text
  formats to stdout.

See Command line for details.
#593.

Performance: 5x–7x faster event processing

The engine's hot paths have been systematically profiled and optimized, resulting in
4.7x–7.7x faster event throughput and 1.9x–2.6x faster setup across all
machine types. All optimizations are internal — no public API changes.
See #592 for details.

Thread safety documentation

The sync engine is thread-safe: multiple threads can send events to the same state
machine instance concurrently. This is now documented in the
processing model and verified by stress tests.
#592.

Coroutine functions as invoke targets

Invoke now supports async def functions and IInvoke handlers with async def run().
On the async engine, coroutines are awaited directly on the event loop instead of running
in a thread executor, making invoke a natural fit for non-blocking async I/O
(e.g., aiohttp, async DB drivers).

async def fetch_data():
    async with aiohttp.ClientSession() as session:
        resp = await session.get("https://api.example.com/data")
        return await resp.json()

class Loader(StateChart):
    loading = State(initial=True, invoke=fetch_data)
    ready = State(final=True)
    done_invoke_loading = loading.to(ready)

See Coroutine functions for details.
#611,
fixes #610.

Bugfixes in 3.1.0

• Fixes silent misuse of Event() with multiple positional arguments. Passing more than one
  transition to Event() (e.g., Event(t1, t2)) now raises InvalidDefinition with a
  clear message suggesting the | operator. Previously, the second argument was silently
  interpreted as the event id, leaving the extra transitions eventless (auto-firing).
  #588.

• Event.name is now auto-humanized from the id (e.g., cycle → Cycle,
  pick_up → Pick up). Diagrams, Mermaid output, and text tables all display
  the human-readable name. Explicit name= values are preserved. The same
  humanize_id() helper is now shared by Event and State.
  #601,
  fixes #600.

• current_state setter now emits DeprecationWarning consistently with the getter.
  Previously only reading current_state triggered the warning; assigning to it was silent.
  The docstring also now includes a deprecated directive for Sphinx autodoc.
  #604.

• Configuration.add()/discard() now write through the model setter, ensuring state
  changes are persisted correctly on domain models (e.g., Django models with custom setters).
  Previously the configuration was updated in-place without notifying the model layer.
  #596.

• States.from_enum() now works correctly inside compound and parallel states. Previously
  the states were silently not collected when used as a nested state declaration.
  #607,
  fixes #606.

Misc in 3.1.0

• Internal refactor of Configuration to always normalize to OrderedSet internally, with
  two boundary helpers (_read_from_model / _write_to_model) confining the
  None | scalar | OrderedSet trichotomy to the model edge. Public API is unchanged.
  #599.

• Reduced allocation overhead in Configuration.add() / discard() by mutating the
  OrderedSet in place and writing back via the setter, removing the ~4–5% overhead
  introduced by the persistence fix in #596.

• Diagram module restructured into a package and doctests in docs/diagram.md replaced by
  the new Sphinx directive; a pre-commit hook now keeps generated diagrams in sync.
  #589,
  #590.

• Bumped the minimum pydot version to 4.0.1 for the diagrams optional extra, plus a
  general refresh of dev dependencies (ruff, pytest-cov, pytest-asyncio, Django, furo, etc.).
  #608.

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=....

StateMachine 2.6.0

February 2026

What's new in 2.6.0

This release adds the StateMachine.enabled_events method, Python 3.14 support,
a significant performance improvement for callback dispatch, and several bugfixes
for async condition expressions, type checker compatibility, and Django integration.

Python compatibility in 2.6.0

StateMachine 2.6.0 supports Python 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14.

Checking enabled events

A new StateMachine.enabled_events method lets you query which events have their
cond/unless guards currently satisfied, going beyond StateMachine.allowed_events
which only checks reachability from the current state.

This is particularly useful for UI scenarios where you want to enable or disable buttons
based on whether an event's conditions are met at runtime.

>>> class ApprovalMachine(StateMachine):
...     pending = State(initial=True)
...     approved = State(final=True)
...     rejected = State(final=True)
...
...     approve = pending.to(approved, cond="is_manager")
...     reject = pending.to(rejected)
...
...     is_manager = False

>>> sm = ApprovalMachine()

>>> [e.id for e in sm.allowed_events]
['approve', 'reject']

>>> [e.id for e in sm.enabled_events()]
['reject']

>>> sm.is_manager = True

>>> [e.id for e in sm.enabled_events()]
['approve', 'reject']

Since conditions may depend on runtime arguments, any *args/**kwargs passed to
enabled_events() are forwarded to the condition callbacks:

>>> class TaskMachine(StateMachine):
...     idle = State(initial=True)
...     running = State(final=True)
...
...     start = idle.to(running, cond="has_enough_resources")
...
...     def has_enough_resources(self, cpu=0):
...         return cpu >= 4

>>> sm = TaskMachine()

>>> sm.enabled_events()
[]

>>> [e.id for e in sm.enabled_events(cpu=8)]
['start']

See Checking enabled events in the Guards documentation for more details.

Performance: cached signature binding

Callback dispatch is now significantly faster thanks to cached signature binding in
SignatureAdapter. The first call to a callback computes the argument binding and
caches a fast-path template; subsequent calls with the same argument shape skip the
full binding logic.

This results in approximately 60% faster bind_expected() calls and
around 30% end-to-end improvement on hot transition paths.

See #548 for benchmarks.

Bugfixes in 2.6.0

• Fixes #531 domain model
  with falsy __bool__ was being replaced by the default Model().
• Fixes #535 async predicates
  in condition expressions (not, and, or) were not being awaited, causing guards to
  silently return incorrect results.
• Fixes #548
  VAR_POSITIONAL and kwargs precedence bugs in the signature binding cache introduced
  by the performance optimization.
• Fixes #511 Pyright/Pylance
  false positive "Argument missing for parameter f" when calling events. Static analyzers
  could not follow the metaclass transformation from TransitionList to Event.
• Fixes #551 MachineMixin
  now gracefully skips state machine initialization for Django historical models in data
  migrations, instead of raising ValueError.
• Fixes #526 sanitize project
  path on Windows for documentation builds.

Misc in 2.6.0

• Added Python 3.14 support #552.
• Upgraded dev dependencies: ruff to 0.15.0, mypy to 1.14.1
  #552.
• Clarified conditional transition evaluation order in documentation
  #546.
• Added pydot DPI resolution settings to diagram documentation
  #514.
• Fixed miscellaneous typos in documentation
  #522.
• Removed Python 3.7 from CI build matrix
  ef351d5.

StateMachine 2.5.0

December 3, 2024

What's new in 2.5.0

This release improves Condition expressions and explicit definition of Events and introduces the helper State.from_.any().

Python compatibility in 2.5.0

StateMachine 2.5.0 supports Python 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, and 3.13.

Helper to declare transition from any state

You can now declare that a state is accessible from any other state with a simple constructor. Using State.from_.any(), the state machine meta class automatically creates transitions from all non-final states to the target state.

Furthermore, both State.from_.itself() and State.to.itself() have been refactored to support type hints and are now fully visible for code completion in your preferred editor.

>>> from statemachine import Event

>>> class AccountStateMachine(StateMachine):
...     active = State("Active", initial=True)
...     suspended = State("Suspended")
...     overdrawn = State("Overdrawn")
...     closed = State("Closed", final=True)
...
...     suspend = Event(active.to(suspended))
...     activate = Event(suspended.to(active))
...     overdraft = Event(active.to(overdrawn))
...     resolve_overdraft = Event(overdrawn.to(active))
...
...     close_account = Event(closed.from_.any(cond="can_close_account"))
...
...     can_close_account: bool = True
...
...     def on_close_account(self):
...         print("Account has been closed.")

>>> sm = AccountStateMachine()
>>> sm.close_account()
Account has been closed.
>>> sm.closed.is_active
True

Allowed events are now bounded to the state machine instance

Since 2.0, the state machine can return a list of allowed events given the current state:

>>> sm = AccountStateMachine()
>>> [str(e) for e in sm.allowed_events]
['suspend', 'overdraft', 'close_account']

Event instances are now bound to the state machine instance, allowing you to pass the event by reference and call it like a method, which triggers the event in the state machine.

You can think of the event as an implementation of the command design pattern.

On this example, we iterate until the state machine reaches a final state,
listing the current state allowed events and executing the simulated user choice:

>>> import random
>>> random.seed("15")

>>> sm = AccountStateMachine()

>>> while not sm.current_state.final:
...     allowed_events = sm.allowed_events
...     print("Choose an action: ")
...     for idx, event in enumerate(allowed_events):
...         print(f"{idx} - {event.name}")
...
...     user_input = random.randint(0, len(allowed_events)-1)
...     print(f"User input: {user_input}")
...
...     event = allowed_events[user_input]
...     print(f"Running the option {user_input} - {event.name}")
...     event()
Choose an action:
0 - Suspend
1 - Overdraft
2 - Close account
User input: 0
Running the option 0 - Suspend
Choose an action:
0 - Activate
1 - Close account
User input: 0
Running the option 0 - Activate
Choose an action:
0 - Suspend
1 - Overdraft
2 - Close account
User input: 2
Running the option 2 - Close account
Account has been closed.

>>> print(f"SM is in {sm.current_state.name} state.")
SM is in Closed state.

Conditions expressions in 2.5.0

This release adds support for comparison operators into Condition expressions.

The following comparison operators are supported:

1. > — Greather than.
2. >= — Greather than or equal.
3. == — Equal.
4. != — Not equal.
5. < — Lower than.
6. <= — Lower than or equal.

Example:

>>> from statemachine import StateMachine, State, Event

>>> class AnyConditionSM(StateMachine):
...     start = State(initial=True)
...     end = State(final=True)
...
...     submit = Event(
...         start.to(end, cond="order_value > 100"),
...         name="finish order",
...     )
...
...     order_value: float = 0

>>> sm = AnyConditionSM()
>>> sm.submit()
Traceback (most recent call last):
TransitionNotAllowed: Can't finish order when in Start.

>>> sm.order_value = 135.0
>>> sm.submit()
>>> sm.current_state.id
'end'

See [Condition expressions](https://python-statemachine.readthedocs.io/en/v2.5.0/guards.html#condition-expressions)  for more details or take a look at the {ref}`sphx_glr_auto_examples_lor_machine.py` example.

Decorator callbacks with explicit event creation in 2.5.0

Now you can add callbacks using the decorator syntax using Events. Note that this syntax is also available without the explicit Event.

>>> from statemachine import StateMachine, State, Event

>>> class StartMachine(StateMachine):
...     created = State(initial=True)
...     started = State(final=True)
...
...     start = Event(created.to(started), name="Launch the machine")
...
...     @start.on
...     def call_service(self):
...         return "calling..."
...

>>> sm = StartMachine()
>>> sm.start()
'calling...'

Bugfixes in 2.5.0

• Fixes #500 issue adding support for Pickle.

Misc in 2.5.0

• We're now using uv #491.
• Simplification of the engines code #498.
• The dispatcher and callback modules where refactored with improved separation of concerns #490.

StateMachine 2.4.0

November 5, 2024

What's new in 2.4.0

This release introduces powerful new features for the StateMachine library: {ref}Condition expressions and explicit definition of {ref}Events. These updates make it easier to define complex transition conditions and enhance performance, especially in workflows with nested or recursive event structures.

Python compatibility in 2.4.0

StateMachine 2.4.0 supports Python 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, and 3.13.

Conditions expressions in 2.4.0

This release introduces support for conditionals with Boolean algebra. You can now use expressions like or, and, and not directly within transition conditions, simplifying the definition of complex state transitions. This allows for more flexible and readable condition setups in your state machine configurations.

Example (with a spoiler of the next highlight):

>>> from statemachine import StateMachine, State, Event

>>> class AnyConditionSM(StateMachine):
...     start = State(initial=True)
...     end = State(final=True)
...
...     submit = Event(
...         start.to(end, cond="used_money or used_credit"),
...         name="finish order",
...     )
...
...     used_money: bool = False
...     used_credit: bool = False

>>> sm = AnyConditionSM()
>>> sm.submit()
Traceback (most recent call last):
TransitionNotAllowed: Can't finish order when in Start.

>>> sm.used_credit = True
>>> sm.submit()
>>> sm.current_state.id
'end'

See {ref}`Condition expressions` for more details or take a look at the {ref}`sphx_glr_auto_examples_lor_machine.py` example.

Explicit event creation in 2.4.0

Now you can explicit declare {ref}Events using the {ref}event class. This allows custom naming, translations, and also helps your IDE to know that events are callable.

>>> from statemachine import StateMachine, State, Event

>>> class StartMachine(StateMachine):
...     created = State(initial=True)
...     started = State(final=True)
...
...     start = Event(created.to(started), name="Launch the machine")
...
>>> [e.id for e in StartMachine.events]
['start']
>>> [e.name for e in StartMachine.events]
['Launch the machine']
>>> StartMachine.start.name
'Launch the machine'

See {ref}`Events` for more details.

Recursive state machines (infinite loop)

We removed a note from the docs saying to avoid recursion loops. Since the {ref}StateMachine 2.0.0 release we've turned the RTC model enabled by default, allowing nested events to occour as all events are put on an internal queue before being executed.

See {ref}`sphx_glr_auto_examples_recursive_event_machine.py` for an example of an infinite loop state machine declaration using `after` action callback to call the same event over and over again.

Bugfixes in 2.4.0

• Fixes #484 issue where nested events inside loops could leak memory by incorrectly referencing previous event_data when queuing the next event. This fix improves performance and stability in event-heavy workflows.

StateMachine 2.3.6

September 11, 2024

Bugfixes in 2.3.6

• Fixes #474 install with extra was not working to install pydot.
• Fixes #480 error when trying to trigger an event inside the initial callback.

StateMachine 2.3.5

September 9, 2024

Python compatibility 2.3.5

Added Python 3.13 on the test matrix. StateMachine 2.3.5 supports Python 3.7, 3.8, 3.9, 3.10, 3.11, 3.12 and 3.13.

Bugfixes in 2.3.5

• Fixes #469 compatibility with pydot 3.0.0+.
• Fixes #473 property support for type checking.

StateMachine 2.3.4

July 11, 2024

Bugfixes in 2.3.4

• Fixes #465 regression that caused exception when registering a listener with unbounded callbacks.

StateMachine 2.3.3

July 3, 2024

Bugfixes in 2.3.3

• Fixes #457 regression that caused backwards incomplatible changes when using Enums. Thanks @hperrey!

Deprecation notes in 2.3.3

Deprecations that will be removed on the next major release:

• The States.from_enum(..., use_enum_instance=True) will be the default.

See {ref}`States from Enum types` for more details.

StateMachine 2.3.2

July 01, 2024

What's new in 2.3.2

Observers are now rebranded to {ref}listeners. With expanted support for adding listeners when instantiating a state machine. This allows covering more use cases. We also improved the async support.

Improved async support

Since version 2.3.0, we have added async support. However, we encountered use cases, such as the async safety on Django ORM, which expects no running event loop and blocks if it detects one on the current thread.

To address this issue, we developed a solution that maintains a unified API for both synchronous and asynchronous operations while effectively handling these scenarios.

This is achieved through a new concept called "engine," an internal strategy pattern abstraction that manages transitions and callbacks.

There are two engines:

SyncEngine : Activated if there are no async callbacks. All code runs exactly as it did before version 2.3.0.

AsyncEngine : Activated if there is at least one async callback. The code runs asynchronously and requires a running event loop, which it will create if none exists.

These engines are internal and are activated automatically by inspecting the registered callbacks in the following scenarios:

See {ref}`async` for more details.

Listeners at class initialization

Listeners are a way to generically add behavior to a state machine without changing its internal implementation.

Example:

>>> from tests.examples.traffic_light_machine import TrafficLightMachine

>>> class LogListener(object):
...     def __init__(self, name):
...         self.name = name
...
...     def after_transition(self, event, source, target):
...         print(f"{self.name} after: {source.id}--({event})-->{target.id}")
...
...     def on_enter_state(self, target, event):
...         print(f"{self.name} enter: {target.id} from {event}")


>>> sm = TrafficLightMachine(listeners=[LogListener("Paulista Avenue")])
Paulista Avenue enter: green from __initial__

>>> sm.cycle()
Running cycle from green to yellow
Paulista Avenue enter: yellow from cycle
Paulista Avenue after: green--(cycle)-->yellow

See {ref}`listeners` for more details.

Binding event triggers to external objects

Now it's possible to bind events to external objets. One expected use case is in conjunction with the {ref}Mixins models, that wrap state machines internally. This way you don't need to expose the state machine.

See {ref}`sphx_glr_auto_examples_user_machine.py` for an example binding event triggers with a state machine.

Bugfixes in 2.3.2

• Fixes #446: Regression that broke sync callbacks interacting with Django ORM due to the added async support and Django's async safety guards.
• Fixes #449: Regression that did not trigger events in nested calls within an already running transition.

Deprecation notes

Statemachine class deprecations in 2.3.2

Deprecations that will be removed on the next major release:

• StateMachine.add_observer is deprecated in favor of StateMachine.add_listener.
• StateMachine.rtc option is deprecated. We'll keep only the run-to-completion (RTC) model.

StateMachine 2.3.1

June 7, 2024

What's new in 2.3.1

This release has a high expected feature, we're adding asynchronous support, and enhancing overall functionality. In fact, the approach we took was to go all the way down changing the internals of the library to be fully async, keeping only the current external API as a thin sync/async adapter.

Python compatibility 2.3.1

StateMachine 2.3.1 supports Python 3.7, 3.8, 3.9, 3.10, 3.11 and 3.12.

We've fixed a bug on the package declaration that was preventing users from Python 3.7 to install the latest version.

Asynchronous Support in 2.3.1

This release introduces native coroutine support using asyncio, enabling seamless integration with asynchronous code.

Now you can send and await for events, and also write async Actions, Conditions and Validators.

>>> class AsyncStateMachine(StateMachine):
...     initial = State('Initial', initial=True)
...     final = State('Final', final=True)
...
...     advance = initial.to(final)

>>> async def run_sm():
...     sm = AsyncStateMachine()
...     await sm.advance()
...     print(sm.current_state)

>>> asyncio.run(run_sm())
Final

StateMachine 2.3.0

June 7, 2024

What's new in 2.3.0

This release has a high expected feature, we're adding asynchronous support, and enhancing overall functionality. In fact, the approach we took was to go all the way down changing the internals of the library to be fully async, keeping only the current external API as a thin sync/async adapter.

Python compatibility 2.3.0

StateMachine 2.3.0 supports Python 3.7, 3.8, 3.9, 3.10, 3.11 and 3.12.

We've fixed a bug on the package declaration that was preventing users from Python 3.7 to install the latest version.

Asynchronous Support in 2.3.0

This release introduces native coroutine support using asyncio, enabling seamless integration with asynchronous code.

Now you can send and await for events, and also write async {ref}Actions, {ref}Conditions and {ref}Validators.

See {ref}`sphx_glr_auto_examples_air_conditioner_machine.py` for an example of
async code with a state machine.

class AsyncStateMachine(StateMachine):
    initial = State("Initial", initial=True)
    final = State("Final", final=True)

    advance = initial.to(final)

    async def on_advance(self):
        return 42


async def run_sm():
    sm = AsyncStateMachine()
    res = await sm.advance()
    return (42, sm.current_state.name)


asyncio.run(run_sm())
# (42, 'Final')

StateMachine 2.2.0

May 6, 2024

What's new in 2.2.0

In this release, we conducted a general cleanup and refactoring across various modules to enhance code readability and maintainability. We improved exception handling and reduced code redundancy.

As a result, we achieved a ~2.2x faster setup in our performance tests and significantly simplified the callback machinery.

Check of unreachable and non-final states

We included one more state machine definition validation for non-final states.

We already check if any states are unreachable from the initial state, if not, an InvalidDefinition exception is thrown.

>>> from statemachine import StateMachine, State

>>> class TrafficLightMachine(StateMachine):
...     "A workflow machine"
...     red = State('Red', initial=True, value=1)
...     green = State('Green', value=2)
...     orange = State('Orange', value=3)
...     hazard = State('Hazard', value=4)
...
...     cycle = red.to(green) | green.to(orange) | orange.to(red)
...     blink = hazard.to.itself()
Traceback (most recent call last):
...
InvalidDefinition: There are unreachable states. The statemachine graph should have a single component. Disconnected states: ['hazard']

From this release, StateMachine will also check that all non-final states have an outgoing transition, and warn you if any states would result in the statemachine becoming trapped in a non-final state with no further transitions possible.

This will currently issue a warning, but can be turned into an exception by setting `strict_states=True` on the class.

>>> from statemachine import StateMachine, State

>>> class TrafficLightMachine(StateMachine, strict_states=True):
...     "A workflow machine"
...     red = State('Red', initial=True, value=1)
...     green = State('Green', value=2)
...     orange = State('Orange', value=3)
...     hazard = State('Hazard', value=4)
...
...     cycle = red.to(green) | green.to(orange) | orange.to(red)
...     fault = red.to(hazard) | green.to(hazard) | orange.to(hazard)
Traceback (most recent call last):
...
InvalidDefinition: All non-final states should have at least one outgoing transition. These states have no outgoing transition: ['hazard']

`strict_states=True` will become the default behavior in the next major release.

See State Transitions.

Bugfixes in 2.2.0

• Fixes #424 allowing deepcopy of state machines.
• Dispatch Mechanism: Resolved issues in the dispatch mechanism in statemachine/dispatcher.py that affected the reliability of event handling across different states. This fix ensures consistent behavior when events are dispatched in complex state machine configurations.

StateMachine 2.1.2

October 6, 2023

This release improves the setup performance of the library by a 10x factor, with a major refactoring on how we handle the callbacks registry and validations.

See #401 for the technical details.

Python compatibility 2.1.2

StateMachine 2.1.2 supports Python 3.7, 3.8, 3.9, 3.10, 3.11 and 3.12.

On the next major release (3.0.0), we will drop support for Python 3.7.

Bugfixes in 2.1.2

• Fixes #406 action callback being called twice when mixing decorator syntax combined with the naming convention.

StateMachine 2.1.1

August 3, 2023

Bugfixes in 2.1.1

• Fixes #391 adding support to pytest-mock spy method.
• Improved factory type hints #399.

StateMachine 2.1.0

June 11, 2023

What's new in 2.1.0

Added support for declaring states using Enum

Given an Enum type that declares our expected states:

>>> from enum import Enum

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

A StateMachine can be declared as follows:

>>> from statemachine import StateMachine
>>> from statemachine.states import States

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

See States from Enum types.

Bugfixes in 2.1.0

• Fixes #369 adding support to wrap methods used as Actions decorated with functools.partial.
• Fixes #384 so multiple observers can watch the same callback.

StateMachine 2.0.0

March 5, 2023

Welcome to StateMachine 2.0.0!

This version is the first to take advantage of the Python3 improvements and is a huge internal refactoring removing the deprecated features on 1.*. We hope that you enjoy it.

These release notes cover the what's new in 2.0, as well as some backward incompatible changes you'll want to be aware of when upgrading from StateMachine 1.*.

Python compatibility in 2.0

StateMachine 2.0 supports Python 3.7, 3.8, 3.9, 3.10, and 3.11.

What's new in 2.0

Run to completion (RTC) by default

There are now two distinct methods for processing events in the library. The new default is to run in RTC model to be compliant with the specs, where the event is put on a queue before processing. You can also configure your state machine to run back in Non-RTC model, where the event will be run immediately and nested events will be chained.

This means that the state machine now completes all the actions associated with an event before moving on to the next event. Even if you trigger an event inside an action.

See processing model for more details.

State names are now optional

State names are now by default derived from the class variable that they are assigned to. You can keep declaring explicit names, but we encourage you to only assign a name when it is different than the one derived from its id.

>>> from statemachine import StateMachine, State

>>> class ApprovalMachine(StateMachine):
...     pending = State(initial=True)
...     waiting_approval = State()
...     approved = State(final=True)
...
...     start = pending.to(waiting_approval)
...     approve = waiting_approval.to(approved)
...

>>> ApprovalMachine.pending.name
'Pending'

>>> ApprovalMachine.waiting_approval.name
'Waiting approval'

>>> ApprovalMachine.approved.name
'Approved'

Added support for internal transitions

An internal transition is like a self transition, but in contrast, no entry or exit actions are ever executed as a result of an internal transition.

>>> from statemachine import StateMachine, State

>>> class TestStateMachine(StateMachine):
...     initial = State(initial=True)
...
...     loop = initial.to.itself(internal=True)

See internal transition for more details.

Added option to ignore unknown events

You can now instantiate a StateMachine with allow_event_without_transition=True, so the state machine will allow triggering events that may not lead to a state transition, including tolerance to unknown event triggers.

The default value is False, that keeps the backward compatible behavior of when an event does not result in a transition, an exception TransitionNotAllowed will be raised.

>>> sm = ApprovalMachine(allow_event_without_transition=True)

>>> sm.send("unknow_event_name")

>>> sm.pending.is_active
True

>>> sm.send("approve")

>>> sm.pending.is_active
True

>>> sm.send("start")

>>> sm.waiting_approval.is_active
True

Added support for translations (i18n)

Now the library messages can be translated into any language.

See Add a translation on how to contribute with translations.

Minor features in 2.0

• Modernization of the development tools to use linters and improved mypy support.
• #342: Guards now supports the evaluation of truthy and falsy values.
• #342: Assignment of Transition guards using decorators is now possible.
• #331: Added a way to generate diagrams using QuickChart.io instead of GraphViz. See diagrams for more details.
• #353: Support for abstract state machine classes, so you can subclass StateMachine to add behavior on your own base class. Abstract StateMachine cannot be instantiated.
• #355: Now is possible to trigger an event as an action by registering the event name as the callback param.

Bugfixes in 2.0

• #341: Fix dynamic dispatch on methods with default parameters.
• #365: Fix transition with multiple events was calling actions of all events.

Backward incompatible changes in 2.0

• Dropped support for Django <= 1.6 for auto-discovering and registering StateMachine classes to be used on django integration.

Statemachine class changes in 2.0

The new processing model (RTC) by default

While we've figured out a way to keep near complete backwards compatible changes to the new Run to completion (RTC) by default feature (all built-in examples run without change), if you encounter problems when upgrading to this version, you can still switch back to the old Non-RTC model. Be aware that we may remove the Non-RTC model in the future.

StateMachine.run removed in favor of StateMachine.send

from tests.examples.traffic_light_machine import TrafficLightMachine

sm = TrafficLightMachine()
sm.run("cycle")

Should become:

>>> from tests.examples.traffic_light_machine import TrafficLightMachine

>>> sm = TrafficLightMachine()
>>> sm.send("cycle")
'Running cycle from green to yellow'

StateMachine.allowed_transitions removed in favor of StateMachine.allowed_events

from tests.examples.traffic_light_machine import TrafficLightMachine

sm = TrafficLightMachine()
assert [t.name for t in sm.allowed_transitions] == ["cycle"]

Should become:

>>> from tests.examples.traffic_light_machine import TrafficLightMachine

>>> sm = TrafficLightMachine()
>>> assert [t.name for t in sm.allowed_events] == ["cycle", "slowdown"]

Statemachine.is_<state> removed in favor of StateMachine.<state>.is_active

from tests.examples.traffic_light_machine import TrafficLightMachine

sm = TrafficLightMachine()
assert sm.is_green

Should become:

>>> from tests.examples.traffic_light_machine import TrafficLightMachine

>>> sm = TrafficLightMachine()
>>> assert sm.green.is_active

State class changes in 2.0

State.identification removed in favor of State.id

from tests.examples.traffic_light_machine import TrafficLightMachine

sm = TrafficLightMachine()
assert sm.current_state.identification == "green"

Should become:

>>> from tests.examples.traffic_light_machine import TrafficLightMachine

>>> sm = TrafficLightMachine()
>>> assert sm.current_state.id == "green"

StateMachine 1.0.3

January 27, 2023

StateMachine 1.0.3 fixes a bug between {ref}State and {ref}transition instances sharing references of callbacks when there were multiple concurrent instances of the same StateMachine class.

Bugfixes

• #334: Fixed a shared reference of callbacks when there were multiple concurrent instances of the same StateMachine class.

StateMachine 1.0.2

January 12, 2023

StateMachine 1.0.2 fixes a regression bug blocking the library usage on Python 3.11.

Bugfixes

• Fixes #316 a bad import of 'inspect.getargspec' that was removed on Python 3.11, still backward compatible with older versions.

StateMachine 1.0.1

January 11, 2023

Welcome to StateMachine 1.0!

This version is a huge refactoring adding a lot of new and exiting features. We hope that you enjoy.

These release notes cover the , as well as some backwards incompatible changes you'll want to be aware of when upgrading from StateMachine 0.9.0 or earlier. We've begun the deprecation process for some features.

Python compatibility in 1.0

StateMachine 1.0 supports Python 2.7, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, and 3.11.

This is the last release to support Python 2.7, 3.5 and 3.6.

What's new in 1.0

Validators and Guards

Transitions now support cond and unless parameters, to restrict the execution.

    class ApprovalMachine(StateMachine):
        "A workflow machine"
        requested = State("Requested", initial=True)
        accepted = State("Accepted")
        rejected = State("Rejected")
        completed = State("Completed")

        validate = requested.to(accepted, cond="is_ok") | requested.to(rejected)

Support for diagrams

You can generate diagrams from your statemachine.

Example:

Unified dispatch mecanism for callbacks (actions and guards)

Every single callback, being actions or guards, is now handled equally by the library.

Also, we've improved the internals in a way that you can implement your callbacks with any number of arbritrary positional or keyword arguments (*args, **kwargs), and the dispatch will match the available arguments with your method signature.

This means that if on your on_enter_<state>() or on_execute_<event>() method, you also need to know the source (state), or the event (event), or access a keyword argument passed with the trigger, you're covered. Just add this parameter to the method and It will be passed by the dispatch mechanics.

Example of what's available:

def action_or_guard_method_name(self, *args, event_data, event, source, state, model, **kwargs):
    pass

Add observers to a running StateMachine

Observers are a way do generically add behaviour to a StateMachine without changing it's internal implementation.

The StateMachine itself is registered as an observer, so by using StateMachine.add_observer() an external object can have the same level of functionalities provided to the built-in class.

Minor features in 1.0

• Fixed mypy complaining about incorrect type for StateMachine class.
• The initial state is now entered when the machine starts. The actions, if defined, on_enter_state and on_enter_<state> are now called.

Backwards incompatible changes in 1.0

Multiple targets from the same origin state

Prior to this release, as we didn't have validators-and-guards, there wasn't an elegant way to declare multiples target states starting from the same pair (event, state). But the library allowed a near-hackish way, by declaring a target state as the result of the on_<event> callback.

So, the previous code (not valid anymore):

class ApprovalMachine(StateMachine):
    "A workflow machine"
    requested = State('Requested', initial=True)
    accepted = State('Accepted')
    rejected = State('Rejected')

    validate = requested.to(accepted, rejected)

    def on_validate(self, current_time):
        if self.model.is_ok():
            self.model.accepted_at = current_time
            return self.accepted
        else:
            return self.rejected

Should be rewriten to use guards, like this:

class ApprovalMachine(StateMachine):
    "A workflow machine"
    requested = State("Requested", initial=True)
    accepted = State("Accepted")
    rejected = State("Rejected")

    validate = requested.to(accepted, conditions="is_ok") | requested.to(rejected)

    def on_validate(self, current_time):
        self.model.accepted_at = current_time

StateMachine now enters the initial state

This issue was reported at #265.

Now StateMachine will execute the actions associated with the on_enter_state and on_enter_<state> when initialized, if they exists.

Integrity is checked at class definition

Statemachine integrity checks are now performed at class declaration (import time) instead of on instance creation. This allows early feedback of invalid definitions.

This was the previous behaviour, you only got an error when trying to instantiate a StateMachine:

class CampaignMachine(StateMachine):
    "A workflow machine"
    draft = State('Draft', initial=True)
    producing = State('Being produced')
    closed = State('Closed', initial=True)  # Should raise an Exception when instantiated

    add_job = draft.to(draft) | producing.to(producing)
    produce = draft.to(producing)
    deliver = producing.to(closed)

with pytest.raises(exceptions.InvalidDefinition):
    CampaignMachine()

Not this is performed as the class definition is performed:

with pytest.raises(exceptions.InvalidDefinition):

    class CampaignMachine(StateMachine):
        "A workflow machine"
        draft = State("Draft", initial=True)
        producing = State("Being produced")
        closed = State(
            "Closed", initial=True
        )  # Should raise an Exception right after the class is defined

        add_job = draft.to(draft) | producing.to(producing)
        produce = draft.to(producing)
        deliver = producing.to(closed)

Other backwards incompatible changes in 1.0

• Due to the check validations and setup performed at the machine initialization, it's now harder to perform monkey-patching to add callbacks at runtime (not a bad thing after all).
• TransitionNotAllowed changed internal attr from transition to event.
• CombinedTransition does not exist anymore. State now holds a flat Transition list called TransitionList that implements de OR operator. This turns a valid StateMachine traversal much easier: [transition for state in machine.states for transition in state.transitions].
• StateMachine.get_transition is removed. See event.
• The previous excetions MultipleStatesFound and MultipleTransitionCallbacksFound are removed. Since now you can have more than one callback defined to the same transition.
• on_enter_state and on_exit_state now accepts any combination of parameters following the dynamic-dispatch rules. Previously it only accepted the state param.
• Transition.__init__ param on_execute renamed to simply on, and now follows the dynamic-dispatch.
• Transition.destinations removed in favor of Transition.target (following SCXML convention). Now each transition only points to a unique target. Each source->target pair is holded by a single Transition.

Deprecated features in 1.0

Statemachine class

• StateMachine.run is deprecated in favor of StateMachine.send.
• StateMachine.allowed_transitions is deprecated in favor of StateMachine.allowed_events.
• Statemachine.is_<state> is deprecated in favor of StateMachine.<state>.is_active.

State class

• State.identification is deprecated in favor of State.id.

StateMachine 1.0.0

January 11, 2023

This release tag was replaced by 1.0.1 due to an error on the metadata when uploading to pypi.

StateMachine 0.9.0

2022-12-21

Python compatibility 0.9.0

StateMachine 0.9 supports Python 2.7, 3.5, 3.6, 3.7, 3.8.

What's new in 0.9

Args and kwargs now are passed to bounded transitions

Parameters sent with the event trigger will now be propagated to the transition handlers.

>>> from statemachine import StateMachine, State

>>> class CampaignMachine(StateMachine):
...     draft = State("Draft", initial=True)
...     producing = State("Being produced")
...
...     produce = draft.to(producing) | producing.to(producing)
...
...     def on_enter_producing(self, approver=None):
...         print(f"Approved by: {approver}")

>>> sm = CampaignMachine()

>>> sm.produce(approver="Aragorn")  # imperative
Approved by: Aragorn

State machine declarations now with final states

Now you can declare final states and the machine will make sure they have no transitions.

>>> from statemachine import StateMachine, State

>>> class ApprovalMachine(StateMachine):
...     """A workflow machine"""
...     requested = State("Requested", initial=True)
...     accepted = State("Accepted")
...     rejected = State("Rejected")
...     completed = State("Completed", final=True)
...
...     validate = requested.to(accepted, cond="is_ok") | requested.to(rejected)
...     release = accepted.to(completed)
...     reopen = completed.to(requested)
Traceback (most recent call last):
...
InvalidDefinition: Cannot declare transitions from final state. Invalid state(s): ['completed']

See {ref}final-state for more details.

Minor features and bug fixes

• Doctesting all documentation including README (with issues on examples fixed).
• Fix state value misjudged when state value is an "boolean False value" (tks @the5fire)
• Fix returning dict as result of transitions callback.

StateMachine 0.8.0

2020-01-23

Python compatibility on 0.8.0

• Add support for Python 3.7 and 3.8 (adding to test matrix).
• Drop official support for Python 3.4 (removing from test matrix, code may still work).

What's new in 0.8

• Update development requirements.
• State machine names should now be fully qualified for mixins, simple names are deprecated and will no longer be supported on a future version.
• Development: Adding mypy linter.
• Add support for State machine inheritance. Thanks @rschrader.
• Add support for reverse transitions: transition = state_a.from_(state_b). Thanks @romulorosa.
• Fix current state equal to destination on enter events. Thanks @robnils and @joshuacc1.
• Check: StateMachine now validates if it's states/transitions graph has only one component. Thanks @rafaelrds.

StateMachine 0.7.1

2019-01-18

• Fix Django integration for registry loading statemachine modules on Django1.7+.

StateMachine 0.7.0

2018-04-01

• New event callbacks: on_enter_<state> and on_exit_<state>.

StateMachine 0.6.2

2017-08-25

• Fix README.

StateMachine 0.6.1

2017-08-25

• Fix deploy issues.

StateMachine 0.6.0

2017-08-25

• Auto-discovering statemachine/statemachines under a Django project when they are requested using the mixin/registry feature.

StateMachine 0.5.1

2017-07-24

• Fix bug on CombinedTransition._can_run not allowing transitions to run if there are more than two transitions combined.

StateMachine 0.5.0

2017-07-13

• Custom exceptions.
• Duplicated definition of on_execute callback is not allowed.
• Fix bug on StateMachine.on_<transition.identifier> being called with extra self param.

StateMachine 0.4.2

2017-07-10

Python compatibility on 0.4.2

• Python 3.6 support.

• Drop official support for Python 3.3.

• Transition can be used as decorator for on_execute callback definition.

• Transition can point to multiple destination states.

StateMachine 0.3.0

2017-03-22

• README getting started section.
• Tests to state machine without model.

StateMachine 0.2.0

2017-03-22

• State can hold a value that will be assigned to the model as the state value.
• Travis-CI integration.
• RTD integration.

StateMachine 0.1.0

2017-03-21

• First release on PyPI.