feat: Nested states (compound / parallel) and support for SCXML (test suit)

.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"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
     - uses: actions/checkout@v4
@@ -33,10 +33,6 @@ jobs:
         cache-suffix: "python${{ matrix.python-version }}"
     - name: Install the project
       run: uv sync --all-extras --dev
-    - name: Install old pydot for 3.7 only
-      if: matrix.python-version == 3.7
-      run: |
-        uv pip install pydot==2.0.0
       #----------------------------------------------
       #              run ruff
       #----------------------------------------------
@@ -50,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

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)
 
 ```
 

conftest.py

@@ -43,3 +43,31 @@ def has_dot_installed():
 def requires_dot_installed(request, has_dot_installed):
     if not has_dot_installed:
         pytest.skip(f"Test {request.node.nodeid} requires 'dot' that is not installed.")
+
+
+# @pytest.fixture(autouse=True, scope="module")
+# def mock_dot_write(request):
+#     """
+#     This fixture avoids updating files while executing tests
+#     """
+
+#     def open_effect(
+#         filename,
+#         mode="r",
+#         *args,
+#         **kwargs,
+#     ):
+#         if mode in ("r", "rt", "rb"):
+#             return open(filename, mode, *args, **kwargs)
+#         elif filename.startswith("/tmp/"):
+#             return open(filename, mode, *args, **kwargs)
+#         elif "b" in mode:
+#             return io.BytesIO()
+#         else:
+#             return io.StringIO()
+
+#     # using global mock instead of the fixture mocker due to the ScopeMismatch
+#     # this fixture is module scoped and mocker is function scoped
+#     with mock.patch("pydot.core.io.open", spec=True) as m:
+#         m.side_effect = open_effect
+#         yield m

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 bounded 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/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/guards.md

@@ -22,7 +22,7 @@ A conditional transition occurs only if specific conditions or criteria are met.
 
 When a transition is conditional, it includes a condition (also known as a _guard_) that must be satisfied for the transition to take place. If the condition is not met, the transition does not occur, and the state machine remains in its current state or follows an alternative path.
 
-This feature allows for multiple transitions on the same {ref}`event`, with each {ref}`transition` checked in the order they are declared. A condition acts like a predicate (a function that evaluates to true/false) and is checked when a {ref}`statemachine` handles an {ref}`event` with a transition from the current state bound to this event. The first transition that meets the conditions (if any) is executed. If none of the transitions meet the conditions, the state machine either raises an exception or does nothing (see the `allow_event_without_transition` parameter of {ref}`StateMachine`).
+This feature allows for multiple transitions on the same {ref}`event`, with each {ref}`transition` checked in the order they are declared. A condition acts like a predicate (a function that evaluates to true/false) and is checked when a {ref}`statemachine` handles an {ref}`event` with a transition from the current state bound to this event. The first transition that meets the conditions (if any) is executed. If none of the transitions meet the conditions, the state machine either raises an exception or does nothing (see the `allow_event_without_transition` class attribute of {ref}`StateMachine`).
 
 When {ref}`transitions` have guards, it is possible to define two or more transitions for the same {ref}`event` from the same {ref}`state`. When the {ref}`event` occurs, the guarded transitions are checked one by one, and the first transition whose guard is true will be executed, while the others will be ignored.
 

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")