feat(scxml): add <invoke> parsing and runtime support

Parse SCXML <invoke> elements and wire them through the existing
Python-level invoke infrastructure (IInvoke protocol, InvokeManager).

Key changes:
- New SCXMLInvoker handler (io/scxml/invoke.py) implementing IInvoke
- Parser support for <invoke>, <content>, <param>, <finalize>, namelist
- Processor wiring: InvokeDefinition → SCXMLInvoker → State(invoke=)
- Engine hooks: handle_external_event for finalize/autoforward routing
- Fix async processing loop early exit resolving caller_future
- Fix finalize running even after invocation terminates (race condition)
- 19 W3C invoke tests now passing (removed from xfail sets)

Author: fgmacedo

statemachine/engines/async_.py

@@ -346,7 +346,7 @@ async def processing_loop(  # noqa: C901
         first_result = self._sentinel
         try:
             took_events = True
-            while took_events:
+            while took_events and self.running:
                 self.clear_cache()
                 took_events = False
                 macrostep_done = False
@@ -406,6 +406,9 @@ async def processing_loop(  # noqa: C901
                         )
                         break
 
+                    # Finalize + autoforward for active invocations
+                    self._invoke_manager.handle_external_event(external_event)
+
                     event_future = external_event.future
                     try:
                         enabled_transitions = await self.select_transitions(external_event)
@@ -451,6 +454,8 @@ async def processing_loop(  # noqa: C901
         result = first_result if first_result is not self._sentinel else None
         # If the caller has a future, await it (already resolved by now).
         if caller_future is not None:
+            # Resolve the future if it wasn't processed (e.g. machine terminated).
+            self._resolve_future(caller_future, result)
             return await caller_future
         return result
 

statemachine/engines/sync.py

@@ -81,7 +81,7 @@ def processing_loop(self, caller_future=None):  # noqa: C901
         first_result = self._sentinel
         try:
             took_events = True
-            while took_events:
+            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
@@ -136,18 +136,9 @@ def processing_loop(self, caller_future=None):  # noqa: C901
                         break
 
                     logger.debug("External event: %s", external_event.event)
-                    # # TODO: Handle cancel event
-                    # if self.is_cancel_event(external_event):
-                    #     self.running = False
-                    #     return
-
-                    # TODO: Invoke states
-                    # for state in self.configuration:
-                    #     for inv in state.invoke:
-                    #         if inv.invokeid == external_event.invokeid:
-                    #             self.apply_finalize(inv, external_event)
-                    #         if inv.autoforward:
-                    #             self.send(inv.id, external_event)
+
+                    # Finalize + autoforward for active invocations
+                    self._invoke_manager.handle_external_event(external_event)
 
                     enabled_transitions = self.select_transitions(external_event)
                     logger.debug("Enabled transitions: %s", enabled_transitions)

statemachine/invoke.py

@@ -290,7 +290,7 @@ def cancel_for_state(self, state: "State"):
         for inv_id, inv in list(self._active.items()):
             if inv.state_id == state.id and not inv.terminated:
                 self._cancel(inv_id)
-        self._pending = [(s, kw) for s, kw in self._pending if s is not state]
+        self._pending = [(s, kw) for s, kw in self._pending if s.id != state.id]
 
     def cancel_all(self):
         """Cancel all active invocations."""
@@ -314,12 +314,13 @@ def spawn_pending_sync(self):
     def _spawn_one_sync(self, callback: "CallbackWrapper", **kwargs):
         state: "State" = kwargs["state"]
         event_kwargs: dict = kwargs.get("event_kwargs", {})
-        ctx = self._make_context(state, event_kwargs)
-        invocation = Invocation(invokeid=ctx.invokeid, state_id=state.id, ctx=ctx)
 
         # Use meta.func to find the original (unwrapped) handler; the callback
         # system wraps everything in a signature_adapter closure.
         handler = self._resolve_handler(callback.meta.func)
+        ctx = self._make_context(state, event_kwargs, handler=handler)
+        invocation = Invocation(invokeid=ctx.invokeid, state_id=state.id, ctx=ctx)
+
         invocation._handler = handler
         self._active[ctx.invokeid] = invocation
 
@@ -347,11 +348,10 @@ def _run_sync_handler(
                 self.sm.send(
                     f"done.invoke.{ctx.invokeid}",
                     data=result,
-                    internal=True,
                 )
         except Exception as e:
             if not ctx.cancelled.is_set():
-                self.sm.send("error.execution", error=e, internal=True)
+                self.sm.send("error.execution", error=e)
         finally:
             invocation.terminated = True
 
@@ -372,10 +372,11 @@ async def spawn_pending_async(self):
     def _spawn_one_async(self, callback: "CallbackWrapper", **kwargs):
         state: "State" = kwargs["state"]
         event_kwargs: dict = kwargs.get("event_kwargs", {})
-        ctx = self._make_context(state, event_kwargs)
-        invocation = Invocation(invokeid=ctx.invokeid, state_id=state.id, ctx=ctx)
 
         handler = self._resolve_handler(callback.meta.func)
+        ctx = self._make_context(state, event_kwargs, handler=handler)
+        invocation = Invocation(invokeid=ctx.invokeid, state_id=state.id, ctx=ctx)
+
         invocation._handler = handler
         self._active[ctx.invokeid] = invocation
 
@@ -404,15 +405,14 @@ async def _run_async_handler(
                 self.sm.send(
                     f"done.invoke.{ctx.invokeid}",
                     data=result,
-                    internal=True,
                 )
         except asyncio.CancelledError:
             # Intentionally swallowed: the owning state was exited, so this
             # invocation was cancelled — there is nothing to propagate.
             return
         except Exception as e:
             if not ctx.cancelled.is_set():
-                self.sm.send("error.execution", error=e, internal=True)
+                self.sm.send("error.execution", error=e)
         finally:
             invocation.terminated = True
 
@@ -434,8 +434,55 @@ def _cancel(self, invokeid: str):
 
     # --- Helpers ---
 
-    def _make_context(self, state: "State", event_kwargs: "dict | None" = None) -> InvokeContext:
-        invokeid = f"{state.id}.{uuid.uuid4().hex[:8]}"
+    def handle_external_event(self, trigger_data) -> None:
+        """Run finalize blocks and autoforward for active invocations.
+
+        Called by the engine before processing each external event.
+        For each active invocation whose handler has ``on_finalize`` or
+        ``on_event`` (autoforward), delegate accordingly.
+        """
+        event_name = str(trigger_data.event) if trigger_data.event else None
+        if event_name is None:
+            return
+
+        # Tag done.invoke events with the invokeid
+        if event_name.startswith("done.invoke."):
+            invokeid = event_name[len("done.invoke.") :]
+            trigger_data.kwargs.setdefault("_invokeid", invokeid)
+
+        for inv in list(self._active.values()):
+            handler = inv._handler
+            if handler is None:
+                continue
+
+            # Check if event originates from this invocation
+            is_from_child = trigger_data.kwargs.get(
+                "_invokeid"
+            ) == inv.invokeid or event_name.startswith(f"done.invoke.{inv.invokeid}")
+
+            # Finalize: run the finalize block if the event came from this invocation.
+            # Note: finalize must run even after the invocation terminates, because
+            # child events may still be queued when the handler thread completes.
+            if is_from_child and hasattr(handler, "on_finalize"):
+                handler.on_finalize(trigger_data)
+
+            # Autoforward: forward parent events to child (not events from child itself).
+            # Only forward if the invocation is still running.
+            if (
+                not inv.terminated
+                and not is_from_child
+                and hasattr(handler, "autoforward")
+                and handler.autoforward
+                and hasattr(handler, "on_event")
+            ):
+                handler.on_event(event_name, **trigger_data.kwargs)
+
+    def _make_context(
+        self, state: "State", event_kwargs: "dict | None" = None, handler: Any = None
+    ) -> InvokeContext:
+        # Use static invoke_id from handler if available (SCXML id= attribute)
+        static_id = getattr(handler, "invoke_id", None) if handler else None
+        invokeid = static_id or f"{state.id}.{uuid.uuid4().hex[:8]}"
         return InvokeContext(
             invokeid=invokeid,
             state_id=state.id,
@@ -453,6 +500,11 @@ def _resolve_handler(underlying: Any) -> "Any | None":
             inner = underlying._invoke_handler
             if isinstance(inner, type) and issubclass(inner, StateChart):
                 return StateChartInvoker(inner)
+            # Return the inner handler directly if it's an IInvoke instance
+            # (e.g., SCXMLInvoker) so duck-typed attributes like invoke_id are accessible.
+            # Exclude classes — @runtime_checkable matches classes that define run().
+            if not isinstance(inner, type) and isinstance(inner, IInvoke):
+                return inner
             return underlying
         if isinstance(underlying, IInvoke):
             return underlying

statemachine/io/scxml/actions.py

@@ -111,36 +111,69 @@ class EventDataWrapper:
 
     def __init__(self, event_data):
         self.event_data = event_data
-        self.sendid = event_data.trigger_data.send_id
-        if event_data.trigger_data.event is None or event_data.trigger_data.event.internal:
-            if "error.execution" == event_data.trigger_data.event:
+        self.trigger_data = event_data.trigger_data
+        td = self.trigger_data
+        self.sendid = td.send_id
+        self.invokeid = td.kwargs.get("_invokeid", "")
+        if td.event is None or td.event.internal:
+            if "error.execution" == td.event:
                 self.type = "platform"
             else:
                 self.type = "internal"
                 self.origintype = ""
         else:
             self.type = "external"
 
+    @classmethod
+    def from_trigger_data(cls, trigger_data):
+        """Create an EventDataWrapper directly from a TriggerData (no EventData needed)."""
+        obj = cls.__new__(cls)
+        obj.event_data = None
+        obj.sendid = trigger_data.send_id
+        obj.trigger_data = trigger_data
+        obj.invokeid = trigger_data.kwargs.get("_invokeid", "")
+        event = trigger_data.event
+        if event is None or event.internal:
+            if "error.execution" == event:
+                obj.type = "platform"
+            else:
+                obj.type = "internal"
+                obj.origintype = ""
+        else:
+            obj.type = "external"
+        return obj
+
     def __getattr__(self, name):
-        return getattr(self.event_data, name)
+        if self.event_data is not None:
+            return getattr(self.event_data, name)
+        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
 
     def __eq__(self, value):
         "This makes SCXML test 329 pass. It assumes that the event is the same instance"
         return isinstance(value, EventDataWrapper)
 
+    @property
+    def _trigger_data(self):
+        if self.event_data is not None:
+            return self.event_data.trigger_data
+        return self.trigger_data
+
     @property
     def name(self):
-        return self.event_data.event
+        if self.event_data is not None:
+            return self.event_data.event
+        return str(self._trigger_data.event) if self._trigger_data.event else None
 
     @property
     def data(self):
         "Property used by the SCXML namespace"
-        if self.trigger_data.kwargs:
-            return _Data(self.trigger_data.kwargs)
-        elif self.trigger_data.args and len(self.trigger_data.args) == 1:
-            return self.trigger_data.args[0]
-        elif self.trigger_data.args:
-            return self.trigger_data.args
+        td = self._trigger_data
+        if td.kwargs:
+            return _Data(td.kwargs)
+        elif td.args and len(td.args) == 1:
+            return td.args[0]
+        elif td.args:
+            return td.args
         else:
             return None
 
@@ -257,7 +290,10 @@ def __init__(self, action: AssignAction):
 
     def __call__(self, *args, **kwargs):
         machine: StateChart = kwargs["machine"]
-        value = _eval(self.action.expr, **kwargs)
+        if self.action.child_xml is not None:
+            value = self.action.child_xml
+        else:
+            value = _eval(self.action.expr, **kwargs)
 
         *path, attr = self.action.location.split(".")
         obj = machine.model
@@ -364,6 +400,26 @@ def raise_action(*args, **kwargs):
     return raise_action
 
 
+def _send_to_parent(action: SendAction, **kwargs):
+    """Route a <send target="#_parent"> to the parent machine via _invoke_session."""
+    machine = kwargs["machine"]
+    session = getattr(machine, "_invoke_session", None)
+    if session is None:
+        return
+    event = action.event or _eval(action.eventexpr, **kwargs)  # type: ignore[arg-type]
+    names = []
+    for name in (action.namelist or "").strip().split():
+        if not hasattr(machine.model, name):
+            raise NameError(f"Namelist variable '{name}' not found on model")
+        names.append(Param(name=name, expr=name))
+    params_values = {}
+    for param in chain(names, action.params):
+        if param.expr is None:
+            continue
+        params_values[param.name] = _eval(param.expr, **kwargs)
+    session.send_to_parent(event, **params_values)
+
+
 def create_send_action_callable(action: SendAction) -> Callable:  # noqa: C901
     content: Any = ()
     _valid_targets = (None, "#_internal", "internal", "#_parent", "parent")
@@ -373,7 +429,7 @@ def create_send_action_callable(action: SendAction) -> Callable:  # noqa: C901
         except (NameError, SyntaxError, TypeError):
             content = (action.content,)
 
-    def send_action(*args, **kwargs):
+    def send_action(*args, **kwargs):  # noqa: C901
         machine: StateChart = kwargs["machine"]
         event = action.event or _eval(action.eventexpr, **kwargs)  # type: ignore[arg-type]
         target = action.target if action.target else None
@@ -393,6 +449,11 @@ def send_action(*args, **kwargs):
                 raise ValueError(f"Invalid target: {target}. Must be one of {_valid_targets}")
             return
 
+        # Handle #_parent target — route to parent via _invoke_session
+        if target == "#_parent":
+            _send_to_parent(action, **kwargs)
+            return
+
         internal = target in ("#_internal", "internal")
 
         send_id = None
@@ -464,6 +525,12 @@ def _create_dataitem_callable(action: DataItem) -> Callable:
     def data_initializer(**kwargs):
         machine: StateChart = kwargs["machine"]
 
+        # Check for invoke param overrides — params from parent override child defaults
+        invoke_params = getattr(machine, "_invoke_params", None)
+        if invoke_params and action.id in invoke_params:
+            setattr(machine.model, action.id, invoke_params[action.id])
+            return
+
         if action.expr:
             try:
                 value = _eval(action.expr, **kwargs)