python-statemachine 3.2.1__py3-none-any.whl → 3.2.2__py3-none-any.whl

statemachine/engines/sync.py

@@ -1,6 +1,7 @@
+from collections.abc import Callable
+from itertools import chain
+from time import monotonic
 from time import sleep
-from time import time
-from typing import TYPE_CHECKING
 
 from statemachine.event import BoundEvent
 from statemachine.orderedset import OrderedSet
@@ -8,26 +9,13 @@ from statemachine.orderedset import OrderedSet
 from ..event_data import TriggerData
 from ..exceptions import InvalidDefinition
 from ..exceptions import TransitionNotAllowed
+from ..state import State
+from ..transition import Transition
 from .base import BaseEngine
-
-if TYPE_CHECKING:
-    from ..transition import Transition
+from .base import _processing_step
 
 
 class SyncEngine(BaseEngine):
-    def _run_microstep(self, enabled_transitions, trigger_data):
-        """Run a microstep for internal/eventless transitions with error handling.
-
-        Note: microstep() handles its own errors internally, so this try/except
-        is a safety net that is not expected to be reached in normal operation.
-        """
-        try:
-            self.microstep(list(enabled_transitions), trigger_data)
-        except InvalidDefinition:
-            raise
-        except Exception as e:  # pragma: no cover
-            self._handle_error(e, trigger_data)
-
     def start(self, **kwargs):
         if self.sm.current_state_value is not None:
             return
@@ -51,12 +39,13 @@ class SyncEngine(BaseEngine):
             transitions = self._initial_transitions(trigger_data)
             self._processing.acquire(blocking=False)
             try:
-                self._enter_states(transitions, trigger_data, OrderedSet(), OrderedSet())
+                with _processing_step(self):
+                    self._enter_states(transitions, trigger_data, OrderedSet(), OrderedSet())
             finally:
                 self._processing.release()
         return self.processing_loop()
 
-    def processing_loop(self, caller_future=None):  # noqa: C901
+    def processing_loop(self):
         """Process event triggers.
 
         The event is put on a queue, and only the first event will have the result collected.
@@ -77,104 +66,231 @@ class SyncEngine(BaseEngine):
         self._debug("%s Processing loop started: %s", self._log_id, self.sm.current_state_value)
         first_result = self._sentinel
         try:
-            took_events = True
-            while took_events and self.running:
-                self.clear_cache()
-                took_events = False
-                # Execute the triggers in the queue in FIFO order until the queue is empty
-                # while self._running and not self.external_queue.is_empty():
-                macrostep_done = False
-                enabled_transitions: "OrderedSet[Transition] | None" = None
-
-                # handles eventless transitions and internal events
-                while not macrostep_done:
-                    self._microstep_count = 0
-                    self._debug(
-                        "%s Macrostep %d: eventless/internal queue",
-                        self._log_id,
-                        self._macrostep_count,
-                    )
-
-                    self.clear_cache()
-                    internal_event = TriggerData(
-                        self.sm, event=None
-                    )  # this one is a "null object"
-                    enabled_transitions = self.select_eventless_transitions(internal_event)
-                    if not enabled_transitions:
-                        if self.internal_queue.is_empty():
-                            macrostep_done = True
-                        else:
-                            internal_event = self.internal_queue.pop()
-                            enabled_transitions = self.select_transitions(internal_event)
-                    if enabled_transitions:
-                        self._debug(
-                            "%s Enabled transitions: %s", self._log_id, enabled_transitions
-                        )
-                        took_events = True
-                        self._run_microstep(enabled_transitions, internal_event)
-
-                # Spawn invoke handlers for states entered during this macrostep.
-                self._invoke_manager.spawn_pending_sync()
-                self._check_root_final_state()
-
-                # Process remaining internal events before external events.
-                # Note: the macrostep loop above already drains the internal queue,
-                # so this is a safety net per SCXML spec for invoke-generated events.
-                while not self.internal_queue.is_empty():  # pragma: no cover
-                    internal_event = self.internal_queue.pop()
-                    enabled_transitions = self.select_transitions(internal_event)
-                    if enabled_transitions:
-                        self._run_microstep(enabled_transitions, internal_event)
-
-                # Process external events
-                self._debug("%s Macrostep %d: external queue", self._log_id, self._macrostep_count)
-                while not self.external_queue.is_empty():
+            with _processing_step(self):
+                took_events = True
+                while took_events and self.running:
                     self.clear_cache()
-                    took_events = True
-                    external_event = self.external_queue.pop()
-                    current_time = time()
-                    if external_event.execution_time > current_time:
-                        self.put(external_event, _delayed=True)
-                        sleep(self.sm._loop_sleep_in_ms)
-                        # Break to Phase 1 so internal events and eventless
-                        # transitions can be processed while we wait.
+                    try:
+                        took_events = self._run_macrostep()
+                        # Spawn invoke handlers for states entered during this macrostep.
+                        self._invoke_manager.spawn_pending_sync()
+                    except Exception:
+                        self.clear()
+                        raise
+                    self._check_root_final_state()
+                    if not self.running:
                         break
 
-                    self._macrostep_count += 1
-                    self._microstep_count = 0
-                    self._debug(
-                        "%s macrostep %d: event=%s",
-                        self._log_id,
-                        self._macrostep_count,
-                        external_event.event,
+                    took_external_events, first_result = self._take_due_external_event(
+                        first_result
                     )
+                    took_events = took_events or took_external_events
 
-                    # Finalize + autoforward for active invocations
-                    self._invoke_manager.handle_external_event(external_event)
-
-                    enabled_transitions = self.select_transitions(external_event)
-                    self._debug("%s Enabled transitions: %s", self._log_id, enabled_transitions)
-                    if enabled_transitions:
-                        try:
-                            result = self.microstep(list(enabled_transitions), external_event)
-                            if first_result is self._sentinel:
-                                first_result = result
-
-                        except Exception:
-                            # We clear the queue as we don't have an expected behavior
-                            # and cannot keep processing
-                            self.clear()
-                            raise
-
-                    else:
-                        if not self.sm.allow_event_without_transition:
-                            raise TransitionNotAllowed(external_event.event, self.sm.configuration)
-
+                if not self.running:
+                    self._drop_external_events()
         finally:
             self._processing.release()
         self._debug("%s Processing loop ended", self._log_id)
         return first_result if first_result is not self._sentinel else None
 
+    def _run_macrostep(self) -> bool:
+        """Take eventless transitions and internal events until neither enables a transition.
+
+        Returns whether any transition was taken. The internal queue is empty on return.
+        """
+        took_events = False
+        while True:
+            self._microstep_count = 0
+            self._debug(
+                "%s Macrostep %d: eventless/internal queue",
+                self._log_id,
+                self._macrostep_count,
+            )
+
+            self.clear_cache()
+            internal_event = TriggerData(self.sm, event=None)  # this one is a "null object"
+            enabled_transitions = self.select_eventless_transitions(internal_event)
+            if not enabled_transitions:
+                if self.internal_queue.is_empty():
+                    return took_events
+                internal_event = self.internal_queue.pop()
+                enabled_transitions = self.select_transitions(internal_event)
+            if enabled_transitions:
+                self._debug("%s Enabled transitions: %s", self._log_id, enabled_transitions)
+                took_events = True
+                self.microstep(list(enabled_transitions), internal_event)
+
+    def _take_due_external_event(self, first_result):
+        """Take the external event at the head of the queue, if it is due.
+
+        One at a time, so the macrostep that follows runs the internal events and eventless
+        transitions it enabled before the next external event is taken.
+
+        Returns whether the queue held an event, and ``first_result`` updated with the result
+        of the first event that enabled a transition.
+        """
+        self._debug("%s Macrostep %d: external queue", self._log_id, self._macrostep_count)
+        if self.external_queue.is_empty():
+            return False, first_result
+
+        self.clear_cache()
+        external_event = self.external_queue.pop_due(monotonic())
+        if external_event is None:
+            sleep(self.sm._loop_sleep_in_ms)
+            return True, first_result
+
+        self._macrostep_count += 1
+        self._microstep_count = 0
+        self._debug(
+            "%s macrostep %d: event=%s",
+            self._log_id,
+            self._macrostep_count,
+            external_event.event,
+        )
+
+        result = self._take_external_event(external_event)
+        if first_result is self._sentinel:
+            first_result = result
+        return True, first_result
+
+    def _take_external_event(self, external_event: TriggerData):
+        """Run one external event.
+
+        Returns the event's microstep result, or the sentinel when it enabled no transition.
+        """
+        # Finalize + autoforward for active invocations
+        self._invoke_manager.handle_external_event(external_event)
+
+        enabled_transitions = self.select_transitions(external_event)
+        self._debug("%s Enabled transitions: %s", self._log_id, enabled_transitions)
+        if not enabled_transitions:
+            if not self.sm.allow_event_without_transition:
+                raise TransitionNotAllowed(external_event.event, self.sm.configuration)
+            return self._sentinel
+
+        try:
+            return self.microstep(list(enabled_transitions), external_event)
+        except Exception:
+            # We clear the queue as we don't have an expected behavior
+            # and cannot keep processing
+            self.clear()
+            raise
+
+    def select_eventless_transitions(self, trigger_data: TriggerData):
+        """
+        Select the eventless transitions that match the trigger data.
+        """
+        return self._select_transitions(trigger_data, lambda t, _e: t.is_eventless)
+
+    def select_transitions(self, trigger_data: TriggerData) -> OrderedSet[Transition]:
+        """
+        Select the transitions that match the trigger data.
+        """
+        return self._select_transitions(trigger_data, lambda t, e: t.match(e))
+
+    def _first_transition_that_matches(
+        self,
+        state: State,
+        trigger_data: TriggerData,
+        predicate: Callable,
+    ) -> "Transition | None":
+        for s in chain([state], state.ancestors()):
+            transition: Transition
+            for transition in s.transitions:
+                if (
+                    not transition.initial
+                    and predicate(transition, trigger_data.event)
+                    and self._conditions_match(transition, trigger_data)
+                ):
+                    return transition
+        return None
+
+    def _select_transitions(
+        self, trigger_data: TriggerData, predicate: Callable
+    ) -> OrderedSet[Transition]:
+        """Select the transitions that match the trigger data."""
+        enabled_transitions = OrderedSet[Transition]()
+
+        # Get atomic states, TODO: sorted by document order
+        atomic_states = (state for state in self.sm.configuration if state.is_atomic)
+
+        for state in atomic_states:
+            transition = self._first_transition_that_matches(state, trigger_data, predicate)
+            if transition is not None:
+                enabled_transitions.add(transition)
+
+        return self._filter_conflicting_transitions(enabled_transitions)
+
+    def microstep(self, transitions: list[Transition], trigger_data: TriggerData):
+        """Process a single set of transitions in a 'lock step'.
+        This includes exiting states, executing transition content, and entering states.
+        """
+        self._microstep_count += 1
+        self._debug(
+            "%s macro:%d micro:%d transitions: %s",
+            self._log_id,
+            self._macrostep_count,
+            self._microstep_count,
+            transitions,
+        )
+        previous_configuration = self.sm.configuration
+        try:
+            result = self._execute_transition_content(
+                transitions, trigger_data, lambda t: t.before.key
+            )
+
+            states_to_exit = self._exit_states(transitions, trigger_data)
+            result += self._enter_states(
+                transitions, trigger_data, states_to_exit, previous_configuration
+            )
+        except InvalidDefinition:
+            self.sm.configuration = previous_configuration
+            raise
+        except Exception as e:
+            self.sm.configuration = previous_configuration
+            self._handle_error(e, trigger_data)
+            return None
+
+        try:
+            self._execute_transition_content(
+                transitions,
+                trigger_data,
+                lambda t: t.after.key,
+                set_target_as_state=True,
+            )
+        except InvalidDefinition:
+            raise
+        except Exception as e:
+            self._handle_error(e, trigger_data)
+
+        if len(result) == 0:
+            result = None
+        elif len(result) == 1:
+            result = result[0]
+
+        return result
+
+    def _exit_states(
+        self, enabled_transitions: list[Transition], trigger_data: TriggerData
+    ) -> OrderedSet[State]:
+        """Compute and process the states to exit for the given transitions."""
+        ordered_states, result = self._prepare_exit_states(enabled_transitions)
+        on_error = self._on_error_handler()
+
+        for info in ordered_states:
+            # Cancel invocations for this state before executing exit handlers.
+            self._invoke_manager.cancel_for_state(info.state)
+
+            args, kwargs = self._get_args_kwargs(info.transition, trigger_data, source=info.state)
+
+            # Execute `onexit` handlers — same per-block error isolation as onentry.
+            self._debug("%s Exiting state: %s", self._log_id, info.state)
+            self.sm._callbacks.call(info.state.exit.key, *args, on_error=on_error, **kwargs)
+
+            self._remove_state_from_configuration(info.state)
+
+        return result
+
     def enabled_events(self, *args, **kwargs):
         sm = self.sm
         enabled = {}

statemachine/event.py

@@ -16,22 +16,22 @@ if TYPE_CHECKING:
     from .transition_list import TransitionList
 
 
-def _expand_event_id(key: str) -> str:
-    """Apply naming conventions for special event prefixes.
+def _expand_event_id(key: str) -> list[str]:
+    """Return the event ids an attribute name declares.
 
-    Converts underscore-based Python attribute names to their dot-separated
-    event equivalents. Returns a space-separated string so ``Events.add()``
-    registers both forms.
+    ``done_invoke_X``, ``done_state_X`` and ``error_X`` also declare their SCXML dotted form
+    (``done.invoke.X``, ``done.state.X``, ``error.X``), each registered as its own event. Any
+    other name declares only itself.
     """
     if key.startswith("done_invoke_"):
         suffix = key[len("done_invoke_") :]
-        return f"{key} done.invoke.{suffix}"
+        return [key, f"done.invoke.{suffix}"]
     if key.startswith("done_state_"):
         suffix = key[len("done_state_") :]
-        return f"{key} done.state.{suffix}"
+        return [key, f"done.state.{suffix}"]
     if key.startswith("error_"):
-        return f"{key} {key.replace('_', '.')}"
-    return key
+        return [key, key.replace("_", ".")]
+    return [key]
 
 
 _event_data_kwargs = {
@@ -46,6 +46,20 @@ _event_data_kwargs = {
 }
 
 
+def raise_delayed_internal(event_id: str):
+    """Reject an event that asks to be both delayed and internal.
+
+    The internal queue runs within the current macrostep, which takes no time.
+    """
+    raise InvalidDefinition(
+        _(
+            "Event {id!r} cannot be both delayed and internal: the internal queue runs "
+            "within the current macrostep, which takes no time. Drop 'internal' to "
+            "deliver it later on the external queue, or drop 'delay' to run it now."
+        ).format(id=event_id)
+    )
+
+
 class Event(AddCallbacksMixin, str):
     """An event triggers a signal that something has happened.
 
@@ -100,6 +114,9 @@ class Event(AddCallbacksMixin, str):
         _has_real_id = id is not None
         id = str(id) if _has_real_id else f"__event__{uuid4().hex}"
 
+        if delay and internal and _has_real_id:
+            raise_delayed_internal(id)
+
         instance = super().__new__(cls, id)
         instance.id = id
         instance.delay = delay
@@ -146,7 +163,9 @@ class Event(AddCallbacksMixin, str):
         """
         if instance is None:
             return self
-        return BoundEvent(id=self.id, name=self.name, delay=self.delay, _sm=instance)
+        return BoundEvent(
+            id=self.id, name=self.name, delay=self.delay, internal=self.internal, _sm=instance
+        )
 
     def put(self, *args, send_id: "str | None" = None, **kwargs):
         # The `__call__` is declared here to help IDEs knowing that an `Event`

statemachine/event_data.py

@@ -1,6 +1,7 @@
 from dataclasses import dataclass
 from dataclasses import field
-from time import time
+from itertools import count
+from time import monotonic
 from typing import TYPE_CHECKING
 from typing import Any
 
@@ -10,6 +11,9 @@ if TYPE_CHECKING:
     from .statemachine import StateChart
     from .transition import Transition
 
+_sequence = count()
+"""Numbers each trigger as it is created, so triggers due at the same time keep their order."""
+
 
 @dataclass(order=True)
 class TriggerData:
@@ -25,7 +29,13 @@ class TriggerData:
     """
 
     execution_time: float = field(default=0.0)
-    """The time at which the :ref:`Event` should run."""
+    """The time at which the :ref:`Event` should run, on the :func:`time.monotonic` clock, so
+    that a step of the wall clock neither holds nor hastens it."""
+
+    sequence: int = field(default=0, init=False)
+    """The order this trigger was created in, which breaks a tie between triggers due at the
+    same time: the queues are priority queues, and without it two triggers stamped alike come
+    out in no particular order."""
 
     model: Any = field(init=False, compare=False)
     """A reference to the underlying model that holds the current :ref:`State`."""
@@ -43,10 +53,16 @@ class TriggerData:
     result (or exception), allowing the caller to ``await`` it.
     """
 
+    cancelled: bool = field(default=False, compare=False, init=False)
+    """Whether :meth:`~statemachine.StateChart.cancel_event` cancelled this trigger. A cancelled
+    trigger stays in its queue, so the triggers around it keep their due order, and is dropped
+    when it reaches the head."""
+
     def __post_init__(self):
         self.model = self.machine.model
         delay = self.event.delay if self.event and self.event.delay else 0
-        self.execution_time = time() + (delay / 1000)
+        self.execution_time = monotonic() + (delay / 1000)
+        self.sequence = next(_sequence)
 
 
 @dataclass

statemachine/events.py

@@ -18,6 +18,9 @@ class Events:
     def __iter__(self):
         return iter(self._items)
 
+    def __contains__(self, event):
+        return event in self._items
+
     def add(self, events):
         if events is None:
             return self
@@ -39,9 +42,9 @@ class Events:
             return self.is_empty
         return any(e.match(event) for e in self)
 
-    def _replace(self, old, new):
+    def _replace(self, old, new_events):
         self._items.remove(old)
-        self._items.append(new)
+        self.add(new_events)
 
     @property
     def is_empty(self):