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

.github/ISSUE_TEMPLATE.md

@@ -13,3 +13,5 @@ Tell us what happened, what went wrong, and what you expected to happen.
 Paste the command(s) you ran and the output.
 If there was a crash, please include the traceback here.
 ```
+
+If you're reporting a bug, consider providing a complete example that can be used directly in the automated tests. We allways write tests to reproduce the issue in order to avoid future regressions.

.github/workflows/python-package.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v4
@@ -46,7 +46,7 @@ jobs:
       #----------------------------------------------
     - name: Test with pytest
       run: |
-        uv run pytest --cov-report=xml:coverage.xml
+        uv run pytest -n auto --cov --cov-report=xml:coverage.xml
         uv run coverage xml
       #----------------------------------------------
       #          upload coverage

.github/workflows/release.yml

@@ -33,7 +33,7 @@ jobs:
 
       - name: Test
         run: |
-          uv run pytest
+          uv run pytest -n auto --cov
 
       - name: Build
         run: |

.pre-commit-config.yaml

@@ -27,7 +27,7 @@ repos:
     pass_filenames: false
   - id: pytest
     name: Pytest
-    entry: uv run pytest
+    entry: uv run pytest -n auto
     types: [python]
     language: system
     pass_filenames: false

AGENTS.md

@@ -51,8 +51,15 @@ uv run pytest tests/test_signature.py::TestSignatureAdapter::test_wrap_fn_single
 uv run pytest -m "not slow"
 ```
 
-Tests include doctests from both source modules (`--doctest-modules`) and markdown docs
-(`--doctest-glob=*.md`). Coverage is enabled by default.
+When trying to run all tests, prefer to use xdist (`-n`) as some SCXML tests uses timeout of 30s to verify fallback mechanism.
+Don't specify the directory `tests/`, because this will exclude doctests from both source modules (`--doctest-modules`) and markdown docs
+(`--doctest-glob=*.md`) (enabled by default):
+
+```bash
+uv run pytest -n auto
+```
+
+Coverage is enabled by default.
 
 ## Linting and formatting
 

README.md

@@ -137,7 +137,7 @@ Or get a complete state representation for debugging purposes:
 
 ```py
 >>> sm.current_state
-State('Yellow', id='yellow', value='yellow', initial=False, final=False)
+State('Yellow', id='yellow', value='yellow', initial=False, final=False, parallel=False)
 
 ```
 

docs/actions.md

@@ -16,6 +16,8 @@ StateMachine in execution.
 There are callbacks that you can specify that are generic and will be called
 when something changes, and are not bound to a specific state or event:
 
+- `prepare_event()`
+
 - `before_transition()`
 
 - `on_exit_state()`
@@ -297,6 +299,32 @@ In addition to {ref}`actions`, you can specify {ref}`validators and guards` that
 See {ref}`conditions` and {ref}`validators`.
 ```
 
+### Preparing events
+
+You can use the `prepare_event` method to add custom information
+that will be included in `**kwargs` to all other callbacks.
+
+A not so usefull example:
+
+```py
+>>> 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'
+
+```
 
 ## Ordering
 
@@ -314,6 +342,10 @@ Actions registered on the same group don't have order guaranties and are execute
     - Action
     - Current state
     - Description
+*   - Preparation
+    - `prepare_event()`
+    - `source`
+    - Add custom event metadata.
 *   - Validators
     - `validators()`
     - `source`

docs/api.md

@@ -1,5 +1,16 @@
 # API
 
+## StateChart
+
+```{versionadded} 3.0.0
+```
+
+```{eval-rst}
+.. autoclass:: statemachine.statemachine.StateChart
+    :members:
+    :undoc-members:
+```
+
 ## StateMachine
 
 ```{eval-rst}
@@ -20,6 +31,16 @@
     :members:
 ```
 
+## HistoryState
+
+```{versionadded} 3.0.0
+```
+
+```{eval-rst}
+.. autoclass:: statemachine.state.HistoryState
+    :members:
+```
+
 ## States (class)
 
 ```{eval-rst}
@@ -79,3 +100,37 @@
 .. autoclass:: statemachine.event_data.EventData
     :members:
 ```
+
+## Callback conventions
+
+These are convention-based callbacks that you can define on your state machine
+subclass. They are not methods on the base class — define them in your subclass
+to enable the behavior.
+
+### `prepare_event`
+
+Called before every event is processed. Returns a `dict` of keyword arguments
+that will be merged into `**kwargs` for all subsequent callbacks (guards, actions,
+entry/exit handlers) during that event's processing:
+
+```python
+class MyMachine(StateMachine):
+    initial = State(initial=True)
+    loop = initial.to.itself()
+
+    def prepare_event(self):
+        return {"request_id": generate_id()}
+
+    def on_loop(self, request_id):
+        # request_id is available here
+        ...
+```
+
+## create_machine_class_from_definition
+
+```{versionadded} 3.0.0
+```
+
+```{eval-rst}
+.. autofunction:: statemachine.io.create_machine_class_from_definition
+```

docs/async.md

@@ -184,3 +184,31 @@ before the event is handled:
 Initial
 
 ```
+
+## StateChart async support
+
+```{versionadded} 3.0.0
+```
+
+`StateChart` works identically with the async engine. All statechart features —
+compound states, parallel states, history pseudo-states, eventless transitions,
+and `done.state` events — are fully supported in async code. The same
+`activate_initial_state()` pattern applies:
+
+```python
+async def run():
+    sm = MyStateChart()
+    await sm.activate_initial_state()
+    await sm.send("event")
+```
+
+### Async-specific limitations
+
+- **Initial state activation**: In async code, you must `await sm.activate_initial_state()`
+  before inspecting `sm.configuration` or `sm.current_state`. In sync code this happens
+  automatically at instantiation time.
+- **Delayed events**: Both sync and async engines support `delay=` on `send()`. The async
+  engine uses `asyncio.sleep()` internally, so it integrates naturally with event loops.
+- **Thread safety**: The processing loop uses a non-blocking lock (`_processing.acquire`).
+  All callbacks run on the same thread they are called from — do not share a state machine
+  instance across threads without external synchronization.

docs/diagram.md

@@ -42,7 +42,7 @@ Graphviz. For example, on Debian-based systems (such as Ubuntu), you can use the
 >>> dot = graph()
 
 >>> dot.to_string()  # doctest: +ELLIPSIS
-'digraph list {...
+'digraph OrderControl {...
 
 ```
 

docs/index.md

@@ -18,6 +18,7 @@ mixins
 integrations
 diagram
 processing_model
+statecharts
 api
 auto_examples/index
 contributing

docs/processing_model.md

@@ -10,19 +10,8 @@ In the literature, It's expected that all state-machine events should execute on
 
 The main point is: What should happen if the state machine triggers nested events while processing a parent event?
 
-```{hint}
-The importance of this decision depends on your state machine definition. Also the difference between RTC
-and non-RTC processing models is more pronounced in a multi-threaded system than in a single-threaded system.
-In other words, even if you run in {ref}`Non-RTC model`, only one external {ref}`event` will be
-handled at a time and all internal events will run before the next external event is called,
-so you only notice the difference if your state machine definition has nested event triggers while
-processing these external events.
-```
-
-There are two distinct models for processing events in the library. The default is to run in
-{ref}`RTC model` to be compliant with the specs, where the {ref}`event` is put on a
-queue before processing. You can also configure your state machine to run in
-{ref}`Non-RTC model`, where the {ref}`event` will be run immediately.
+This library atheres to the {ref}`RTC model` to be compliant with the specs, where the {ref}`event` is put on a
+queue before processing.
 
 Consider this state machine:
 
@@ -60,13 +49,13 @@ Consider this state machine:
 
 In a run-to-completion (RTC) processing model (**default**), the state machine executes each event to completion before processing the next event. This means that the state machine completes all the actions associated with an event before moving on to the next event. This guarantees that the system is always in a consistent state.
 
-If the machine is in `rtc` mode, the event is put on a queue.
+Internally, the events are put on a queue before processing.
 
 ```{note}
-While processing the queue items, if others events are generated, they will be processed sequentially.
+While processing the queue items, if others events are generated, they will be processed sequentially in FIFO order.
 ```
 
-Running the above state machine will give these results on the RTC model:
+Running the above state machine will give these results:
 
 ```py
 >>> sm = ServerConnection()
@@ -88,51 +77,3 @@ after 'connection_succeed' from 'connecting' to 'connected'
 ```{note}
 Note that the events `connect` and `connection_succeed` are executed sequentially, and the `connect.after` runs on the expected order.
 ```
-
-## Non-RTC model
-
-```{deprecated} 2.3.2
-`StateMachine.rtc` option is deprecated. We'll keep only the **run-to-completion** (RTC) model.
-```
-
-In contrast, in a non-RTC (synchronous) processing model, the state machine starts executing nested events
-while processing a parent event. This means that when an event is triggered, the state machine
-chains the processing when another event was triggered as a result of the first event.
-
-```{warning}
-This can lead to complex and unpredictable behavior in the system if your state-machine definition triggers **nested
-events**.
-```
-
-If your state machine does not trigger nested events while processing a parent event,
-and you plan to use the API in an _imperative programming style_, you can consider using the synchronous mode (non-RTC).
-
-In this model, you can think of events as analogous to simple method calls.
-
-```{note}
-While processing the {ref}`event`, if others events are generated, they will also be processed immediately, so a **nested** behavior happens.
-```
-
-Running the above state machine will give these results on the non-RTC (synchronous) model:
-
-```py
->>> sm = ServerConnection(rtc=False)
-enter 'disconnected' from '' given '__initial__'
-
->>> sm.send("connect")
-exit 'disconnected' to 'connecting' given 'connect'
-on 'connect' from 'disconnected' to 'connecting'
-enter 'connecting' from 'disconnected' given 'connect'
-exit 'connecting' to 'connected' given 'connection_succeed'
-on 'connection_succeed' from 'connecting' to 'connected'
-enter 'connected' from 'connecting' given 'connection_succeed'
-after 'connection_succeed' from 'connecting' to 'connected'
-after 'connect' from 'disconnected' to 'connecting'
-['on_transition', 'on_connect']
-
-```
-
-```{note}
-Note that the events `connect` and `connection_succeed` are nested, and the `connect.after`
-unexpectedly only runs after `connection_succeed.after`.
-```

docs/releases/2.0.0.md

@@ -89,7 +89,10 @@ including tolerance to unknown {ref}`event` triggers.
 The default value is ``False``, that keeps the backward compatible behavior of when an
 event does not result in a {ref}`transition`, an exception ``TransitionNotAllowed`` will be raised.
 
-```py
+```
+>>> import pytest
+>>> pytest.skip("Since 3.0.0 `allow_event_without_transition` is now a class attribute.")
+
 >>> sm = ApprovalMachine(allow_event_without_transition=True)
 
 >>> sm.send("unknow_event_name")