feat: New callback

Author: fgmacedo

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/releases/3.0.0.md

@@ -14,6 +14,42 @@ StateMachine 3.0.0 supports Python 3.9, 3.10, 3.11, 3.12, and 3.13.
 
 Now a condition can check if the state machine current set of active states (a.k.a `configuration`) contains a state using the syntax  `cond="In('<state-id>')"`.
 
+### 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'
+
+```
+
+### Event matching following SCXML spec
+
+Now events matching follows the SCXML spec.
+
+For example, a transition with an `event` attribute of `"error foo"` will match event names `error`, `error.send`, `error.send.failed`, etc. (or `foo`, `foo.bar` etc.)
+but would not match events named `errors.my.custom`, `errorhandler.mistake`, `error.send` or `foobar`.
+
+An event designator consisting solely of `*` can be used as a wildcard matching any sequence of tokens, and thus any event.
+
 
 ## Bugfixes in 3.0.0
 

pyproject.toml

@@ -53,6 +53,7 @@ dev = [
     "sphinx-copybutton >=0.5.2",
     "pdbr>=0.8.9",
     "pytest-xdist>=3.6.1",
+    "pytest-timeout>=2.3.1",
 ]
 
 [build-system]

statemachine/callbacks.py

@@ -43,6 +43,7 @@ class SpecReference(IntFlag):
 
 
 class CallbackGroup(IntEnum):
+    PREPARE = auto()
     ENTER = auto()
     EXIT = auto()
     VALIDATOR = auto()

statemachine/engines/base.py

@@ -103,26 +103,13 @@ def start(self):
         if self.sm.current_state_value is not None:
             return
 
-        BoundEvent("__initial__", _sm=self.sm).put(machine=self.sm)
+        BoundEvent("__initial__", _sm=self.sm).put()
 
     def _initial_transition(self, trigger_data):
         transition = Transition(State(), self.sm._get_initial_state(), event="__initial__")
         transition._specs.clear()
         return transition
 
-    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 _conditions_match(self, transition: Transition, trigger_data: TriggerData):
-        event_data = EventData(trigger_data=trigger_data, transition=transition)
-        args, kwargs = event_data.args, event_data.extended_kwargs
-
-        self.sm._callbacks.call(transition.validators.key, *args, **kwargs)
-        return self.sm._callbacks.all(transition.cond.key, *args, **kwargs)
-
     def _filter_conflicting_transitions(
         self, transitions: OrderedSet[Transition]
     ) -> OrderedSet[Transition]:
@@ -234,6 +221,12 @@ def get_effective_target_states(self, transition: Transition) -> OrderedSet[Stat
         # TODO: Handle history states
         return OrderedSet([transition.target])
 
+    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.
@@ -297,6 +290,27 @@ def microstep(self, transitions: List[Transition], trigger_data: TriggerData):
 
         return result
 
+    def _get_args_kwargs(
+        self, transition: Transition, trigger_data: TriggerData, set_target_as_state: bool = False
+    ):
+        # TODO: Ideally this method should be called only once per microstep/transition
+        event_data = EventData(trigger_data=trigger_data, transition=transition)
+        if set_target_as_state:
+            event_data.state = transition.target
+
+        args, kwargs = event_data.args, event_data.extended_kwargs
+
+        result = self.sm._callbacks.call(self.sm.prepare.key, *args, **kwargs)
+        for new_kwargs in result:
+            kwargs.update(new_kwargs)
+        return args, kwargs
+
+    def _conditions_match(self, transition: Transition, trigger_data: TriggerData):
+        args, kwargs = self._get_args_kwargs(transition, trigger_data)
+
+        self.sm._callbacks.call(transition.validators.key, *args, **kwargs)
+        return self.sm._callbacks.all(transition.cond.key, *args, **kwargs)
+
     def _exit_states(self, enabled_transitions: List[Transition], trigger_data: TriggerData):
         """Compute and process the states to exit for the given transitions."""
         states_to_exit = self._compute_exit_set(enabled_transitions)
@@ -309,8 +323,7 @@ def _exit_states(self, enabled_transitions: List[Transition], trigger_data: Trig
         # states_to_exit = sorted(states_to_exit, key=self.exit_order)
 
         for info in states_to_exit:
-            event_data = EventData(trigger_data=trigger_data, transition=info.transition)
-            args, kwargs = event_data.args, event_data.extended_kwargs
+            args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
 
             # # TODO: Update history
             # for history in state.history:
@@ -342,10 +355,9 @@ def _execute_transition_content(
     ):
         result = []
         for transition in enabled_transitions:
-            event_data = EventData(trigger_data=trigger_data, transition=transition)
-            if set_target_as_state:
-                event_data.state = transition.target
-            args, kwargs = event_data.args, event_data.extended_kwargs
+            args, kwargs = self._get_args_kwargs(
+                transition, trigger_data, set_target_as_state=set_target_as_state
+            )
 
             result += self.sm._callbacks.call(get_key(transition), *args, **kwargs)
 
@@ -379,14 +391,14 @@ def _enter_states(
         )
 
         # Sort states to enter in entry order
-        # for state in sorted(states_to_enter, key=self.entry_order):   # TODO: ordegin of states_to_enter # noqa: E501
+        # for state in sorted(states_to_enter, key=self.entry_order):   # TODO: order of states_to_enter # noqa: E501
         for info in states_to_enter:
             target = info.target
             assert target
             transition = info.transition
-            event_data = EventData(trigger_data=trigger_data, transition=transition)
-            event_data.state = target
-            args, kwargs = event_data.args, event_data.extended_kwargs
+            args, kwargs = self._get_args_kwargs(
+                transition, trigger_data, set_target_as_state=True
+            )
 
             # Add state to the configuration
             # self.sm.configuration |= {target}
@@ -400,7 +412,6 @@ def _enter_states(
             #     state.is_first_entry = False
 
             # Execute `onentry` handlers
-            # TODO: if not transition.internal:
             self.sm._callbacks.call(target.enter.key, *args, **kwargs)
 
             # Handle default initial states
@@ -420,18 +431,15 @@ def _enter_states(
                     parent = target.parent
                     grandparent = parent.parent
 
-                    self.internal_queue.put(
-                        BoundEvent(f"done.state.{parent.id}", _sm=self.sm).build_trigger(
-                            machine=self.sm
-                        )
-                    )
+                    BoundEvent(
+                        f"done.state.{parent.id}",
+                        _sm=self.sm,
+                        internal=True,
+                    ).put()
+
                     if grandparent.parallel:
                         if all(child.final for child in grandparent.states):
-                            self.internal_queue.put(
-                                BoundEvent(f"done.state.{parent.id}", _sm=self.sm).build_trigger(
-                                    machine=self.sm
-                                )
-                            )
+                            BoundEvent(f"done.state.{parent.id}", _sm=self.sm, internal=True).put()
 
     def compute_entry_set(
         self, transitions, states_to_enter, states_for_default_entry, default_history_content
@@ -521,7 +529,6 @@ def add_descendant_states_to_enter(
         assert state
 
         if state.parallel:
-            # Handle parallel states
             for child_state in state.states:
                 if not any(s.target.is_descendant(child_state) for s in states_to_enter):
                     info_to_add = StateTransition(
@@ -536,7 +543,6 @@ def add_descendant_states_to_enter(
                         default_history_content,
                     )
         elif state.is_compound:
-            # Handle compound states
             states_for_default_entry.add(info)
             initial_state = next(s for s in state.states if s.initial)
             transition = next(

statemachine/engines/sync.py

@@ -113,7 +113,7 @@ def processing_loop(self):  # noqa: C901
                         sleep(0.001)
                         continue
 
-                    logger.debug("External event: %s", external_event)
+                    logger.debug("External event: %s", external_event.event)
                     # # TODO: Handle cancel event
                     # if self.is_cancel_event(external_event):
                     #     self.running = False

statemachine/event.py

@@ -1,5 +1,6 @@
 from typing import TYPE_CHECKING
 from typing import List
+from typing import cast
 from uuid import uuid4
 
 from .callbacks import CallbackGroup
@@ -118,13 +119,14 @@ def __get__(self, instance, owner):
             return self
         return BoundEvent(id=self.id, name=self.name, delay=self.delay, _sm=instance)
 
-    def put(self, *args, machine: "StateMachine", send_id: "str | None" = None, **kwargs):
+    def put(self, *args, send_id: "str | None" = None, **kwargs):
         # The `__call__` is declared here to help IDEs knowing that an `Event`
         # can be called as a method. But it is not meant to be called without
         # an SM instance. Such SM instance is provided by `__get__` method when
         # used as a property descriptor.
-        trigger_data = self.build_trigger(*args, machine=machine, send_id=send_id, **kwargs)
-        machine._put_nonblocking(trigger_data, internal=self.internal)
+        assert self._sm is not None
+        trigger_data = self.build_trigger(*args, machine=self._sm, send_id=send_id, **kwargs)
+        self._sm._put_nonblocking(trigger_data, internal=self.internal)
         return trigger_data
 
     def build_trigger(
@@ -154,9 +156,8 @@ def __call__(self, *args, **kwargs):
         # can be called as a method. But it is not meant to be called without
         # an SM instance. Such SM instance is provided by `__get__` method when
         # used as a property descriptor.
-        machine = self._sm
-        self.put(*args, machine=machine, **kwargs)
-        return machine._processing_loop()
+        self.put(*args, **kwargs)
+        return self._sm._processing_loop()
 
     def split(  # type: ignore[override]
         self, sep: "str | None" = None, maxsplit: int = -1
@@ -167,7 +168,31 @@ def split(  # type: ignore[override]
         return [Event(event) for event in result]
 
     def match(self, event: str) -> bool:
-        return self == event or self == "*"
+        if self == "*":
+            return True
+
+        # Normalize descriptor by removing trailing '.*' or '.'
+        # to handle cases like 'error', 'error.', 'error.*'
+        descriptor = cast(str, self)
+        if descriptor.endswith(".*"):
+            descriptor = descriptor[:-2]
+        elif descriptor.endswith("."):
+            descriptor = descriptor[:-1]
+
+        # Check prefix match:
+        # The descriptor must be a prefix of the event.
+        # Split both descriptor and event into tokens
+        descriptor_tokens = descriptor.split(".") if descriptor else []
+        event_tokens = event.split(".") if event else []
+
+        if len(descriptor_tokens) > len(event_tokens):
+            return False
+
+        for d_token, e_token in zip(descriptor_tokens, event_tokens):  # noqa: B905
+            if d_token != e_token:
+                return False
+
+        return True
 
 
 class BoundEvent(Event):

statemachine/factory.py

@@ -6,6 +6,9 @@
 from typing import Tuple
 
 from . import registry
+from .callbacks import CallbackGroup
+from .callbacks import CallbackPriority
+from .callbacks import CallbackSpecList
 from .event import Event
 from .exceptions import InvalidDefinition
 from .graph import iterate_states
@@ -43,7 +46,10 @@ def __init__(
         cls._events: Dict[Event, None] = {}  # used Dict to preserve order and avoid duplicates
         cls._protected_attrs: set = set()
         cls._events_to_update: Dict[Event, Event | None] = {}
-
+        cls._specs = CallbackSpecList()
+        cls.prepare = cls._specs.grouper(CallbackGroup.PREPARE).add(
+            "prepare_event", priority=CallbackPriority.GENERIC, is_convention=True
+        )
         cls.add_inherited(bases)
         cls.add_from_attributes(attrs)
         cls._unpack_builders_callbacks()