feat: New statechartengine for experimentation without breaking all the tests

Author: fgmacedo

docs/_static/custom_machine.css

@@ -28,6 +28,7 @@
 
 }
 
+
 /* Gallery Donwload buttons */
 div.sphx-glr-download a {
     color: #404040 !important;

docs/states.md

@@ -17,6 +17,7 @@ How to define and attach [](actions.md) to {ref}`States`.
 
 A {ref}`StateMachine` should have one and only one `initial` {ref}`state`.
 
+If not specified, the default initial state is the first child state in document order.
 
 The initial {ref}`state` is entered when the machine starts and the corresponding entering
 state {ref}`actions` are called if defined.

statemachine/engines/async_.py

@@ -1,25 +1,17 @@
-from threading import Lock
-from typing import TYPE_CHECKING
-from weakref import proxy
-
 from ..event_data import EventData
 from ..event_data import TriggerData
 from ..exceptions import InvalidDefinition
 from ..exceptions import TransitionNotAllowed
 from ..i18n import _
 from ..transition import Transition
-
-if TYPE_CHECKING:
-    from ..statemachine import StateMachine
+from .base import BaseEngine
 
 
-class AsyncEngine:
-    def __init__(self, sm: "StateMachine", rtc: bool = True):
-        self.sm = proxy(sm)
-        self._sentinel = object()
+class AsyncEngine(BaseEngine):
+    def __init__(self, sm, rtc: bool = True):
         if not rtc:
             raise InvalidDefinition(_("Only RTC is supported on async engine"))
-        self._processing = Lock()
+        super().__init__(sm, rtc)
 
     async def activate_initial_state(self):
         """
@@ -63,16 +55,16 @@ async def processing_loop(self):
         first_result = self._sentinel
         try:
             # Execute the triggers in the queue in FIFO order until the queue is empty
-            while self.sm._external_queue:
-                trigger_data = self.sm._external_queue.popleft()
+            while self._external_queue:
+                trigger_data = self._external_queue.popleft()
                 try:
                     result = await self._trigger(trigger_data)
                     if first_result is self._sentinel:
                         first_result = result
                 except Exception:
                     # Whe clear the queue as we don't have an expected behavior
                     # and cannot keep processing
-                    self.sm._external_queue.clear()
+                    self._external_queue.clear()
                     raise
         finally:
             self._processing.release()

statemachine/engines/base.py

@@ -0,0 +1,34 @@
+from collections import deque
+from threading import Lock
+from typing import TYPE_CHECKING
+from weakref import proxy
+
+from ..event_data import TriggerData
+
+if TYPE_CHECKING:
+    from ..statemachine import StateMachine
+
+
+class BaseEngine:
+    def __init__(self, sm: "StateMachine", rtc: bool = True) -> None:
+        self.sm = proxy(sm)
+        self._external_queue: deque = deque()
+        self._sentinel = object()
+        self._rtc = rtc
+        self._processing = Lock()
+        self._put_initial_activation_trigger_on_queue()
+
+    def _put_nonblocking(self, trigger_data: TriggerData):
+        """Put the trigger on the queue without blocking the caller."""
+        self._external_queue.append(trigger_data)
+
+    def _put_initial_activation_trigger_on_queue(self):
+        # Activate the initial state, this only works if the outer scope is sync code.
+        # for async code, the user should manually call `await sm.activate_initial_state()`
+        # after state machine creation.
+        if self.sm.current_state_value is None:
+            trigger_data = TriggerData(
+                machine=self.sm,
+                event="__initial__",
+            )
+            self._put_nonblocking(trigger_data)

statemachine/engines/statechart.py

@@ -0,0 +1,130 @@
+from ..event_data import EventData
+from ..event_data import TriggerData
+from ..exceptions import TransitionNotAllowed
+from ..transition import Transition
+from .base import BaseEngine
+
+
+class StateChartEngine(BaseEngine):
+    def __init__(self, sm, rtc: bool = True):
+        super().__init__(sm, rtc)
+        self.activate_initial_state()
+
+    def activate_initial_state(self):
+        """
+        Activate the initial state.
+
+        Called automatically on state machine creation from sync code, but in
+        async code, the user must call this method explicitly.
+
+        Given how async works on python, there's no built-in way to activate the initial state that
+        may depend on async code from the StateMachine.__init__ method.
+        """
+        return self.processing_loop()
+
+    def processing_loop(self):
+        """Process event triggers.
+
+        The simplest implementation is the non-RTC (synchronous),
+        where the trigger will be run immediately and the result collected as the return.
+
+        .. note::
+
+            While processing the trigger, if others events are generated, they
+            will also be processed immediately, so a "nested" behavior happens.
+
+        If the machine is on ``rtc`` model (queued), the event is put on a queue, and only the
+        first event will have the result collected.
+
+        .. note::
+            While processing the queue items, if others events are generated, they
+            will be processed sequentially (and not nested).
+
+        """
+        if not self._rtc:
+            # The machine is in "synchronous" mode
+            trigger_data = self._external_queue.popleft()
+            return self._trigger(trigger_data)
+
+        # We make sure that only the first event enters the processing critical section,
+        # next events will only be put on the queue and processed by the same loop.
+        if not self._processing.acquire(blocking=False):
+            return None
+
+        # We will collect the first result as the processing result to keep backwards compatibility
+        # so we need to use a sentinel object instead of `None` because the first result may
+        # be also `None`, and on this case the `first_result` may be overridden by another result.
+        first_result = self._sentinel
+        try:
+            # Execute the triggers in the queue in FIFO order until the queue is empty
+            while self._external_queue:
+                trigger_data = self._external_queue.popleft()
+                try:
+                    result = self._trigger(trigger_data)
+                    if first_result is self._sentinel:
+                        first_result = result
+                except Exception:
+                    # Whe clear the queue as we don't have an expected behavior
+                    # and cannot keep processing
+                    self._external_queue.clear()
+                    raise
+        finally:
+            self._processing.release()
+        return first_result if first_result is not self._sentinel else None
+
+    def _trigger(self, trigger_data: TriggerData):
+        event_data = None
+        if trigger_data.event == "__initial__":
+            transition = Transition(None, self.sm._get_initial_state(), event="__initial__")
+            transition._specs.clear()
+            event_data = EventData(trigger_data=trigger_data, transition=transition)
+            self._activate(event_data)
+            return self._sentinel
+
+        state = self.sm.current_state
+        for transition in state.transitions:
+            if not transition.match(trigger_data.event):
+                continue
+
+            event_data = EventData(trigger_data=trigger_data, transition=transition)
+            args, kwargs = event_data.args, event_data.extended_kwargs
+            self.sm._get_callbacks(transition.validators.key).call(*args, **kwargs)
+            if not self.sm._get_callbacks(transition.cond.key).all(*args, **kwargs):
+                continue
+
+            result = self._activate(event_data)
+            event_data.result = result
+            event_data.executed = True
+            break
+        else:
+            if not self.sm.allow_event_without_transition:
+                raise TransitionNotAllowed(trigger_data.event, state)
+
+        return event_data.result if event_data else None
+
+    def _activate(self, event_data: EventData):
+        args, kwargs = event_data.args, event_data.extended_kwargs
+        transition = event_data.transition
+        source = event_data.state
+        target = transition.target
+
+        result = self.sm._get_callbacks(transition.before.key).call(*args, **kwargs)
+        if source is not None and not transition.internal:
+            self.sm._get_callbacks(source.exit.key).call(*args, **kwargs)
+
+        result += self.sm._get_callbacks(transition.on.key).call(*args, **kwargs)
+
+        self.sm.current_state = target
+        event_data.state = target
+        kwargs["state"] = target
+
+        if not transition.internal:
+            self.sm._get_callbacks(target.enter.key).call(*args, **kwargs)
+        self.sm._get_callbacks(transition.after.key).call(*args, **kwargs)
+
+        if len(result) == 0:
+            result = None
+        elif len(result) == 1:
+            result = result[0]
+
+        return result

statemachine/engines/sync.py

@@ -1,22 +1,13 @@
-from threading import Lock
-from typing import TYPE_CHECKING
-from weakref import proxy
-
 from ..event_data import EventData
 from ..event_data import TriggerData
 from ..exceptions import TransitionNotAllowed
 from ..transition import Transition
-
-if TYPE_CHECKING:
-    from ..statemachine import StateMachine
+from .base import BaseEngine
 
 
-class SyncEngine:
-    def __init__(self, sm: "StateMachine", rtc: bool = True):
-        self.sm = proxy(sm)
-        self._sentinel = object()
-        self._rtc = rtc
-        self._processing = Lock()
+class SyncEngine(BaseEngine):
+    def __init__(self, sm, rtc: bool = True):
+        super().__init__(sm, rtc)
         self.activate_initial_state()
 
     def activate_initial_state(self):
@@ -52,7 +43,7 @@ def processing_loop(self):
         """
         if not self._rtc:
             # The machine is in "synchronous" mode
-            trigger_data = self.sm._external_queue.popleft()
+            trigger_data = self._external_queue.popleft()
             return self._trigger(trigger_data)
 
         # We make sure that only the first event enters the processing critical section,
@@ -66,16 +57,16 @@ def processing_loop(self):
         first_result = self._sentinel
         try:
             # Execute the triggers in the queue in FIFO order until the queue is empty
-            while self.sm._external_queue:
-                trigger_data = self.sm._external_queue.popleft()
+            while self._external_queue:
+                trigger_data = self._external_queue.popleft()
                 try:
                     result = self._trigger(trigger_data)
                     if first_result is self._sentinel:
                         first_result = result
                 except Exception:
                     # Whe clear the queue as we don't have an expected behavior
                     # and cannot keep processing
-                    self.sm._external_queue.clear()
+                    self._external_queue.clear()
                     raise
         finally:
             self._processing.release()

statemachine/factory.py

@@ -10,6 +10,7 @@
 from .event import Event
 from .event import trigger_event_factory
 from .exceptions import InvalidDefinition
+from .graph import iterate_states
 from .graph import iterate_states_and_transitions
 from .graph import visit_connected_states
 from .i18n import _
@@ -44,6 +45,7 @@ def __init__(
 
         cls.add_inherited(bases)
         cls.add_from_attributes(attrs)
+        cls._unpack_builders_callbacks()
 
         if not cls.states:
             return
@@ -196,6 +198,15 @@ def _setup(cls):
             "send",
         } | {s.id for s in cls.states}
 
+    def _unpack_builders_callbacks(cls):
+        callbacks = {}
+        for state in iterate_states(cls.states):
+            if state._callbacks:
+                callbacks.update(state._callbacks)
+                del state._callbacks
+        for key, value in callbacks.items():
+            setattr(cls, key, value)
+
     def add_inherited(cls, bases):
         for base in bases:
             for state in getattr(base, "states", []):

statemachine/graph.py

@@ -18,3 +18,12 @@ def iterate_states_and_transitions(states):
     for state in states:
         yield state
         yield from state.transitions
+        if state.states:
+            yield from iterate_states_and_transitions(state.states)
+
+
+def iterate_states(states):
+    for state in states:
+        yield state
+        if state.states:
+            yield from iterate_states(state.states)

statemachine/state.py

@@ -23,14 +23,17 @@ def __new__(  # type: ignore [misc]
             return super().__new__(cls, classname, bases, attrs)  # type: ignore [return-value]
 
         states = []
+        callbacks = {}
         for key, value in attrs.items():
             if isinstance(value, State):
                 value._set_id(key)
                 states.append(value)
-            if isinstance(value, TransitionList):
+            elif isinstance(value, TransitionList):
                 value.add_event(key)
+            elif callable(value):
+                callbacks[key] = value
 
-        return State(name=name, states=states, **kwargs)
+        return State(name=name, states=states, _callbacks=callbacks, **kwargs)
 
 
 class State:
@@ -51,6 +54,7 @@ class State:
             value.
         initial: Set ``True`` if the ``State`` is the initial one. There must be one and only
             one initial state in a statemachine. Defaults to ``False``.
+            If not specified, the default initial state is the first child state in document order.
         final: Set ``True`` if represents a final state. A machine can have
             optionally many final states. Final states have no :ref:`transition` starting from It.
             Defaults to ``False``.
@@ -144,6 +148,7 @@ def __init__(
         states: Any = None,
         enter: Any = None,
         exit: Any = None,
+        _callbacks: Any = None,
     ):
         self.name = name
         self.value = value
@@ -153,6 +158,7 @@ def __init__(
         self._initial = initial
         self._final = final
         self._id: str = ""
+        self._callbacks = _callbacks
         self.parent: "State" = None
         self.transitions = TransitionList()
         self._specs = CallbackSpecList()