feat: propagate event kwargs to invoke handlers

Forward keyword arguments from the triggering event to invoke handlers:
- Plain callables receive them via SignatureAdapter dependency injection
- IInvoke handlers receive them via ctx.kwargs

This allows patterns like sm.send("start", file_name="config.json")
where the invoke handler reads file_name as a parameter.

Author: fgmacedo

docs/invoke.md

@@ -174,8 +174,8 @@ matching any invoke completion for that state regardless of the specific invoke
 ## IInvoke protocol
 
 For advanced use cases, implement the `IInvoke` protocol. This gives you access to
-the `InvokeContext` — with the invoke ID, cancellation signal, and a reference to the
-parent machine:
+the `InvokeContext` — with the invoke ID, cancellation signal, event kwargs, and a
+reference to the parent machine:
 
 ```py
 >>> from statemachine.invoke import IInvoke, InvokeContext
@@ -188,6 +188,7 @@ parent machine:
 ...         # ctx.cancelled — threading.Event, set when state exits
 ...         # ctx.send — send events to parent machine
 ...         # ctx.machine — reference to parent machine
+...         # ctx.kwargs — keyword arguments from the triggering event
 ...         path = ctx.machine.file_path
 ...         return Path(path).read_text()
 ...
@@ -263,6 +264,46 @@ Events from cancelled invocations are silently ignored.
 
 ```
 
+## Event data propagation
+
+When a state with invoke handlers is entered via an event, the keyword arguments from
+that event are forwarded to the invoke handlers. Plain callables receive them via
+{ref}`SignatureAdapter <actions>` dependency injection; `IInvoke` handlers receive them
+via `ctx.kwargs`:
+
+```py
+>>> config_file = Path(tempfile.mktemp(suffix=".json"))
+>>> _ = config_file.write_text('{"debug": true}')
+
+>>> class ConfigByName(StateChart):
+...     idle = State(initial=True)
+...     loading = State()
+...     ready = State(final=True)
+...     start = idle.to(loading)
+...     done_invoke_loading = loading.to(ready)
+...
+...     def on_invoke_loading(self, file_name=None, **kwargs):
+...         """file_name comes from send('start', file_name=...)."""
+...         return json.loads(Path(file_name).read_text())
+...
+...     def on_enter_ready(self, data=None, **kwargs):
+...         self.config = data
+
+>>> sm = ConfigByName()
+>>> sm.send("start", file_name=str(config_file))
+>>> time.sleep(0.2)
+
+>>> "ready" in sm.configuration_values
+True
+>>> sm.config
+{'debug': True}
+
+>>> config_file.unlink()
+
+```
+
+For initial states (entered automatically, not via an event), `kwargs` is empty.
+
 ## Error handling
 
 If an invoke handler raises an exception, `error.execution` is sent to the machine's

statemachine/engines/async_.py

@@ -248,7 +248,7 @@ async def _enter_states(  # noqa: C901
 
             # Mark state for invocation if it has invoke callbacks registered
             if target.invoke.key in self.sm._callbacks:
-                self._invoke_manager.mark_for_invoke(target)
+                self._invoke_manager.mark_for_invoke(target, trigger_data.kwargs)
 
             # Handle final states
             if target.final:

statemachine/engines/base.py

@@ -653,7 +653,7 @@ def _enter_states(  # noqa: C901
 
             # Mark state for invocation if it has invoke callbacks registered
             if target.invoke.key in self.sm._callbacks:
-                self._invoke_manager.mark_for_invoke(target)
+                self._invoke_manager.mark_for_invoke(target, trigger_data.kwargs)
 
             # Handle final states
             if target.final:

statemachine/invoke.py

@@ -19,10 +19,9 @@
 from typing import Callable
 from typing import Dict
 from typing import List
+from typing import Tuple
 from typing import runtime_checkable
 
-from .orderedset import OrderedSet
-
 try:
     from typing import Protocol
 except ImportError:  # pragma: no cover
@@ -150,6 +149,9 @@ class InvokeContext:
     cancelled: threading.Event = field(default_factory=threading.Event)
     """Set when the owning state is exited; handlers should check this to stop early."""
 
+    kwargs: dict = field(default_factory=dict)
+    """Keyword arguments from the event that triggered the state entry."""
+
 
 @dataclass
 class Invocation:
@@ -263,24 +265,32 @@ class InvokeManager:
     def __init__(self, engine: "BaseEngine"):
         self._engine = engine
         self._active: Dict[str, Invocation] = {}
-        self._states_to_invoke: "OrderedSet[State]" = OrderedSet()
+        self._pending: "List[Tuple[State, dict]]" = []
 
     @property
     def sm(self) -> "StateChart":
         return self._engine.sm
 
     # --- Engine hooks ---
 
-    def mark_for_invoke(self, state: "State"):
-        """Called by ``_enter_states()`` after entering a state with invoke callbacks."""
-        self._states_to_invoke.add(state)
+    def mark_for_invoke(self, state: "State", event_kwargs: "dict | None" = None):
+        """Called by ``_enter_states()`` after entering a state with invoke callbacks.
+
+        Args:
+            state: The state that was entered.
+            event_kwargs: Keyword arguments from the event that triggered the
+                state entry.  These are forwarded to invoke handlers via
+                dependency injection (plain callables) and ``InvokeContext.kwargs``
+                (IInvoke handlers).
+        """
+        self._pending.append((state, event_kwargs or {}))
 
     def cancel_for_state(self, state: "State"):
         """Called by ``_exit_states()`` before exiting a 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._states_to_invoke.discard(state)
+        self._pending = [(s, kw) for s, kw in self._pending if s is not state]
 
     def cancel_all(self):
         """Cancel all active invocations."""
@@ -291,17 +301,20 @@ def cancel_all(self):
 
     def spawn_pending_sync(self):
         """Spawn invoke handlers for all states marked for invocation (sync engine)."""
-        for state in sorted(self._states_to_invoke, key=lambda s: s.document_order):
+        pending = sorted(self._pending, key=lambda p: p[0].document_order)
+        self._pending.clear()
+        for state, event_kwargs in pending:
             self.sm._callbacks.visit(
                 state.invoke.key,
                 self._spawn_one_sync,
                 state=state,
+                event_kwargs=event_kwargs,
             )
-        self._states_to_invoke.clear()
 
     def _spawn_one_sync(self, callback: "CallbackWrapper", **kwargs):
         state: "State" = kwargs["state"]
-        ctx = self._make_context(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
@@ -329,7 +342,7 @@ def _run_sync_handler(
             if handler is not None:
                 result = handler.run(ctx)
             else:
-                result = callback.call(ctx=ctx, machine=ctx.machine)
+                result = callback.call(ctx=ctx, machine=ctx.machine, **ctx.kwargs)
             if not ctx.cancelled.is_set():
                 self.sm.send(
                     f"done.invoke.{ctx.invokeid}",
@@ -346,17 +359,20 @@ def _run_sync_handler(
 
     async def spawn_pending_async(self):
         """Spawn invoke handlers for all states marked for invocation (async engine)."""
-        for state in sorted(self._states_to_invoke, key=lambda s: s.document_order):
+        pending = sorted(self._pending, key=lambda p: p[0].document_order)
+        self._pending.clear()
+        for state, event_kwargs in pending:
             await self.sm._callbacks.async_visit(
                 state.invoke.key,
                 self._spawn_one_async,
                 state=state,
+                event_kwargs=event_kwargs,
             )
-        self._states_to_invoke.clear()
 
     def _spawn_one_async(self, callback: "CallbackWrapper", **kwargs):
         state: "State" = kwargs["state"]
-        ctx = self._make_context(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)
@@ -382,7 +398,7 @@ async def _run_async_handler(
                 result = await loop.run_in_executor(None, handler.run, ctx)
             else:
                 result = await loop.run_in_executor(
-                    None, lambda: callback.call(ctx=ctx, machine=ctx.machine)
+                    None, lambda: callback.call(ctx=ctx, machine=ctx.machine, **ctx.kwargs)
                 )
             if not ctx.cancelled.is_set():
                 self.sm.send(
@@ -418,13 +434,14 @@ def _cancel(self, invokeid: str):
 
     # --- Helpers ---
 
-    def _make_context(self, state: "State") -> InvokeContext:
+    def _make_context(self, state: "State", event_kwargs: "dict | None" = None) -> InvokeContext:
         invokeid = f"{state.id}.{uuid.uuid4().hex[:8]}"
         return InvokeContext(
             invokeid=invokeid,
             state_id=state.id,
             send=self.sm.send,
             machine=self.sm,
+            kwargs=event_kwargs or {},
         )
 
     @staticmethod

tests/test_invoke.py

@@ -489,6 +489,76 @@ def on_enter_ready(self, data=None, **kwargs):
         assert all_results[1] == [2]
 
 
+class TestInvokeEventKwargs:
+    """Event kwargs from send() are forwarded to invoke handlers."""
+
+    async def test_plain_callable_receives_event_kwargs(self, sm_runner):
+        """Plain callable invoke handler receives event kwargs via SignatureAdapter."""
+        received = []
+
+        class SM(StateChart):
+            idle = State(initial=True)
+            loading = State()
+            ready = State(final=True)
+            start = idle.to(loading)
+            done_invoke_loading = loading.to(ready)
+
+            def on_invoke_loading(self, file_name=None, **kwargs):
+                received.append(file_name)
+                return f"loaded:{file_name}"
+
+            def on_enter_ready(self, data=None, **kwargs):
+                received.append(data)
+
+        sm = await sm_runner.start(SM)
+        await sm_runner.send(sm, "start", file_name="config.json")
+        await sm_runner.sleep(0.15)
+        await sm_runner.processing_loop(sm)
+
+        assert "ready" in sm.configuration_values
+        assert received == ["config.json", "loaded:config.json"]
+
+    async def test_iinvoke_handler_receives_event_kwargs_via_ctx(self, sm_runner):
+        """IInvoke handler receives event kwargs via ctx.kwargs."""
+        received = []
+
+        class FileLoader:
+            def run(self, ctx: InvokeContext):
+                received.append(ctx.kwargs.get("file_name"))
+                return f"loaded:{ctx.kwargs['file_name']}"
+
+        class SM(StateChart):
+            idle = State(initial=True)
+            loading = State(invoke=FileLoader)
+            ready = State(final=True)
+            start = idle.to(loading)
+            done_invoke_loading = loading.to(ready)
+
+            def on_enter_ready(self, data=None, **kwargs):
+                received.append(data)
+
+        sm = await sm_runner.start(SM)
+        await sm_runner.send(sm, "start", file_name="data.csv")
+        await sm_runner.sleep(0.15)
+        await sm_runner.processing_loop(sm)
+
+        assert "ready" in sm.configuration_values
+        assert received == ["data.csv", "loaded:data.csv"]
+
+    async def test_initial_state_invoke_has_empty_kwargs(self, sm_runner):
+        """Invoke on initial state gets empty kwargs (no triggering event)."""
+
+        class SM(StateChart):
+            loading = State(initial=True, invoke=lambda: 42)
+            ready = State(final=True)
+            done_invoke_loading = loading.to(ready)
+
+        sm = await sm_runner.start(SM)
+        await sm_runner.sleep(0.15)
+        await sm_runner.processing_loop(sm)
+        assert "ready" in sm.configuration_values
+
+
 class TestInvokeNotTriggeredOnNonInvokeState:
     """States without invoke handlers should not be affected."""