feat: implement error.execution event handling per SCXML spec

Add `error_on_execution` flag (True on StateChart, False on StateMachine
for backward compat) that catches runtime exceptions in callbacks and
queues an `error.execution` internal event instead of propagating.

Error handling is layered by responsibility:
- callbacks.call(on_error=...): per-block isolation for onentry/onexit
  — errors in one block don't affect other blocks
- callbacks.all(on_error=...): condition errors treated as False
- Engine._conditions_match: delegates to callbacks.all with on_error
- Engine.microstep: catches errors in transition actions with rollback
- SCXML if_action: condition errors treated as false (SCXML translation)
- InvalidDefinition always propagates regardless of error_on_execution

Also fixes:
- Event with custom id in factory (preserve SCXML event ids like
  "error.execution" while keeping Python attribute accessible)
- SCXML _event system variable initialized to None before first event
- Infinite loop guard for error.execution in transition handlers

Author: fgmacedo

statemachine/callbacks.py

@@ -314,17 +314,33 @@ async def async_all(self, *args, **kwargs):
                 return False
         return True
 
-    def call(self, *args, **kwargs):
-        return [
-            callback.call(*args, **kwargs)
-            for callback in self
-            if callback.condition(*args, **kwargs)
-        ]
-
-    def all(self, *args, **kwargs):
+    def call(self, *args, on_error: "Callable[[Exception], None] | None" = None, **kwargs):
+        if on_error is None:
+            return [
+                callback.call(*args, **kwargs)
+                for callback in self
+                if callback.condition(*args, **kwargs)
+            ]
+
+        results = []
+        for callback in self:
+            if callback.condition(*args, **kwargs):
+                try:
+                    results.append(callback.call(*args, **kwargs))
+                except Exception as e:
+                    on_error(e)
+        return results
+
+    def all(self, *args, on_error: "Callable[[Exception], None] | None" = None, **kwargs):
         for condition in self:
-            if not condition.call(*args, **kwargs):
-                return False
+            try:
+                if not condition.call(*args, **kwargs):
+                    return False
+            except Exception as e:
+                if on_error is not None:
+                    on_error(e)
+                    return False
+                raise
         return True
 
 
@@ -361,18 +377,30 @@ def async_or_sync(self):
             callback._iscoro for executor in self._registry.values() for callback in executor
         )
 
-    def call(self, key: str, *args, **kwargs):
+    def call(
+        self,
+        key: str,
+        *args,
+        on_error: "Callable[[Exception], None] | None" = None,
+        **kwargs,
+    ):
         if key not in self._registry:
             return []
-        return self._registry[key].call(*args, **kwargs)
+        return self._registry[key].call(*args, on_error=on_error, **kwargs)
 
     def async_call(self, key: str, *args, **kwargs):
         return self._registry[key].async_call(*args, **kwargs)
 
-    def all(self, key: str, *args, **kwargs):
+    def all(
+        self,
+        key: str,
+        *args,
+        on_error: "Callable[[Exception], None] | None" = None,
+        **kwargs,
+    ):
         if key not in self._registry:
             return True
-        return self._registry[key].all(*args, **kwargs)
+        return self._registry[key].all(*args, on_error=on_error, **kwargs)
 
     def async_all(self, key: str, *args, **kwargs):
         return self._registry[key].async_all(*args, **kwargs)

statemachine/engines/async_.py

@@ -4,6 +4,7 @@
 
 from ..event_data import EventData
 from ..event_data import TriggerData
+from ..exceptions import InvalidDefinition
 from ..exceptions import TransitionNotAllowed
 from .base import BaseEngine
 
@@ -91,14 +92,27 @@ async def _trigger(self, trigger_data: TriggerData):
 
         return result if executed else None
 
-    async def _activate(self, trigger_data: TriggerData, transition: "Transition"):
-        event_data = EventData(trigger_data=trigger_data, transition=transition)
-        args, kwargs = event_data.args, event_data.extended_kwargs
-
-        await self.sm._callbacks.async_call(transition.validators.key, *args, **kwargs)
-        if not await self.sm._callbacks.async_all(transition.cond.key, *args, **kwargs):
-            return False, None
+    async def _async_conditions_match(
+        self, transition: "Transition", trigger_data: TriggerData, args, kwargs
+    ):
+        if self.sm.error_on_execution:
+            try:
+                await self.sm._callbacks.async_call(transition.validators.key, *args, **kwargs)
+                return await self.sm._callbacks.async_all(transition.cond.key, *args, **kwargs)
+            except InvalidDefinition:
+                raise
+            except Exception as e:
+                self._send_error_execution(trigger_data, e)
+                return False
+        else:
+            await self.sm._callbacks.async_call(transition.validators.key, *args, **kwargs)
+            return await self.sm._callbacks.async_all(transition.cond.key, *args, **kwargs)
 
+    async def _async_execute_transition(
+        self, transition: "Transition", event_data: EventData, trigger_data: TriggerData
+    ):
+        """Execute transition callbacks (before, exit, on, enter) with error handling."""
+        args, kwargs = event_data.args, event_data.extended_kwargs
         source = transition.source
         target = transition.target
 
@@ -116,7 +130,34 @@ async def _activate(self, trigger_data: TriggerData, transition: "Transition"):
 
         if not transition.internal:
             await self.sm._callbacks.async_call(target.enter.key, *args, **kwargs)
-        await self.sm._callbacks.async_call(transition.after.key, *args, **kwargs)
+        return result
+
+    async def _activate(self, trigger_data: TriggerData, transition: "Transition"):
+        event_data = EventData(trigger_data=trigger_data, transition=transition)
+        args, kwargs = event_data.args, event_data.extended_kwargs
+
+        if not await self._async_conditions_match(transition, trigger_data, args, kwargs):
+            return False, None
+
+        try:
+            result = await self._async_execute_transition(transition, event_data, trigger_data)
+        except InvalidDefinition:
+            raise
+        except Exception as e:
+            if self.sm.error_on_execution:
+                self._send_error_execution(trigger_data, e)
+                return True, None
+            raise
+
+        try:
+            await self.sm._callbacks.async_call(transition.after.key, *args, **kwargs)
+        except InvalidDefinition:
+            raise
+        except Exception as e:
+            if self.sm.error_on_execution:
+                self._send_error_execution(trigger_data, e)
+            else:
+                raise
 
         if len(result) == 0:
             result = None

statemachine/engines/base.py

@@ -18,6 +18,7 @@
 from ..event import Event
 from ..event_data import EventData
 from ..event_data import TriggerData
+from ..exceptions import InvalidDefinition
 from ..exceptions import TransitionNotAllowed
 from ..orderedset import OrderedSet
 from ..state import HistoryState
@@ -119,6 +120,34 @@ def cancel_event(self, send_id: str):
         """Cancel the event with the given send_id."""
         self.external_queue.remove(send_id)
 
+    @property
+    def _on_error_execution(self):
+        """Return an error handler for per-block error isolation, or None.
+
+        When ``error_on_execution`` is enabled, returns a handler that queues
+        ``error.execution`` on the internal queue.  Otherwise returns ``None``
+        so that exceptions propagate normally.
+        """
+        if self.sm.error_on_execution:
+
+            def _handler(e: Exception):
+                if isinstance(e, InvalidDefinition):
+                    raise
+                self.sm.send("error.execution", error=e, internal=True)
+
+            return _handler
+        return None
+
+    def _send_error_execution(self, trigger_data: TriggerData, error: Exception):
+        """Send error.execution to internal queue (SCXML spec).
+
+        If already processing an error.execution event, ignore to avoid infinite loops.
+        """
+        if trigger_data.event and str(trigger_data.event) == "error.execution":
+            logger.warning("Error while processing error.execution, ignoring: %s", error)
+            return
+        self.sm.send("error.execution", error=error, internal=True)
+
     def start(self):
         if self.sm.current_state_value is not None:
             return
@@ -321,15 +350,30 @@ def microstep(self, transitions: List[Transition], trigger_data: TriggerData):
             result += self._enter_states(
                 transitions, trigger_data, states_to_exit, previous_configuration
             )
-        except Exception:
+        except InvalidDefinition:
             self.sm.configuration = previous_configuration
             raise
-        self._execute_transition_content(
-            transitions,
-            trigger_data,
-            lambda t: t.after.key,
-            set_target_as_state=True,
-        )
+        except Exception as e:
+            self.sm.configuration = previous_configuration
+            if self.sm.error_on_execution:
+                self._send_error_execution(trigger_data, e)
+                return None
+            raise
+
+        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:
+            if self.sm.error_on_execution:
+                self._send_error_execution(trigger_data, e)
+            else:
+                raise
 
         if len(result) == 0:
             result = None
@@ -366,8 +410,12 @@ def _get_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)
+        self.sm._callbacks.call(
+            transition.validators.key, *args, on_error=self._on_error_execution, **kwargs
+        )
+        return self.sm._callbacks.all(
+            transition.cond.key, *args, on_error=self._on_error_execution, **kwargs
+        )
 
     def _exit_states(
         self, enabled_transitions: List[Transition], trigger_data: TriggerData
@@ -405,9 +453,11 @@ def _exit_states(
         for info in ordered_states:
             args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
 
-            # Execute `onexit` handlers
+            # Execute `onexit` handlers — same per-block error isolation as onentry.
             if info.state is not None:  # TODO: and not info.transition.internal:
-                self.sm._callbacks.call(info.state.exit.key, *args, **kwargs)
+                self.sm._callbacks.call(
+                    info.state.exit.key, *args, on_error=self._on_error_execution, **kwargs
+                )
 
             # TODO: Cancel invocations
             # for invocation in state.invoke:
@@ -503,8 +553,11 @@ def _enter_states(  # noqa: C901
             #     self.initialize_data_model(state)
             #     state.is_first_entry = False
 
-            # Execute `onentry` handlers
-            on_entry_result = self.sm._callbacks.call(target.enter.key, *args, **kwargs)
+            # Execute `onentry` handlers — each handler is a separate block per
+            # SCXML spec: errors in one block MUST NOT affect other blocks.
+            on_entry_result = self.sm._callbacks.call(
+                target.enter.key, *args, on_error=self._on_error_execution, **kwargs
+            )
 
             # Handle default initial states
             if target.id in {t.state.id for t in states_for_default_entry if t.state}:

statemachine/engines/sync.py

@@ -7,6 +7,7 @@
 from statemachine.orderedset import OrderedSet
 
 from ..event_data import TriggerData
+from ..exceptions import InvalidDefinition
 from ..exceptions import TransitionNotAllowed
 from .base import BaseEngine
 
@@ -17,6 +18,18 @@
 
 
 class SyncEngine(BaseEngine):
+    def _run_microstep(self, enabled_transitions, trigger_data):
+        """Run a microstep for internal/eventless transitions with error handling."""
+        try:
+            self.microstep(list(enabled_transitions), trigger_data)
+        except InvalidDefinition:
+            raise
+        except Exception as e:
+            if self.sm.error_on_execution:
+                self._send_error_execution(trigger_data, e)
+            else:
+                raise
+
     def start(self):
         if self.sm.current_state_value is not None:
             return
@@ -91,7 +104,7 @@ def processing_loop(self):  # noqa: C901
                     if enabled_transitions:
                         logger.debug("Enabled transitions: %s", enabled_transitions)
                         took_events = True
-                        self.microstep(list(enabled_transitions), internal_event)
+                        self._run_microstep(enabled_transitions, internal_event)
 
                 # TODO: Invoke platform-specific logic
                 # for state in sorted(self.states_to_invoke, key=self.entry_order):
@@ -104,7 +117,7 @@ def processing_loop(self):  # noqa: C901
                     internal_event = self.internal_queue.pop()
                     enabled_transitions = self.select_transitions(internal_event)
                     if enabled_transitions:
-                        self.microstep(list(enabled_transitions), internal_event)
+                        self._run_microstep(enabled_transitions, internal_event)
 
                 # Process external events
                 logger.debug("Macrostep: external queue")
@@ -141,7 +154,7 @@ def processing_loop(self):  # noqa: C901
                                 first_result = result
 
                         except Exception:
-                            # Whe clear the queue as we don't have an expected behavior
+                            # We clear the queue as we don't have an expected behavior
                             # and cannot keep processing
                             self.clear()
                             raise

statemachine/factory.py

@@ -247,14 +247,16 @@ def add_from_attributes(cls, attrs):  # noqa: C901
             elif isinstance(value, (Transition, TransitionList)):
                 cls.add_event(event=Event(transitions=value, id=key, name=key))
             elif isinstance(value, (Event,)):
-                cls.add_event(
-                    event=Event(
-                        transitions=value._transitions,
-                        id=key,
-                        name=value.name,
-                    ),
-                    old_event=value,
+                event_id = value.id if value._has_real_id else key
+                new_event = Event(
+                    transitions=value._transitions,
+                    id=event_id,
+                    name=value.name,
                 )
+                cls.add_event(event=new_event, old_event=value)
+                # Ensure the event is accessible by the Python attribute name
+                if event_id != key:
+                    setattr(cls, key, new_event)
             elif getattr(value, "attr_name", None):
                 cls._add_unbounded_callback(key, value)