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

This PR introduces comprehensive SCXML support to the library, including the full processing model, hierarchical/parallel/history states, internal and multi-target transitions, delayed events (send/cancel), and donedata.

It achieves sync/async engine parity, implements spec-compliant error handling (error.execution, error.communication) with proper isolation and safety guards, and significantly improves W3C SCXML test conformance.

The change also includes major architectural refactors across the parser, engines, and state model, enhanced diagram generation for compound/parallel/history states, and expanded test coverage to ~100%, with Python ≥3.9 compatibility.

Overall, this PR elevates the project to a fully functional, spec-aligned SCXML implementation with stronger reliability and internal design.

Author: fgmacedo

.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 {...
 
 ```