perf: cache signature binding results (#550)

* ## Description

The `signature_adapter` causes significant overhead in hot transition paths due to repeated signature binding on every callback invocation. This PR implements caching for `bind_expected()` to avoid recomputing argument bindings when the kwargs pattern is unchanged.

## Root Cause

The `SignatureAdapter.bind_expected()` method iterates through all parameters and matches them against the provided kwargs on every invocation. In typical state machine usage, callbacks are invoked repeatedly with the same kwargs keys (e.g., `source`, `target`, `event`), making this repeated computation wasteful.

## Fix

Added a per-instance cache (`_bind_cache`) to `SignatureAdapter` that stores "binding templates" based on the arguments structure:

- **Cache key**: `(len(args), frozenset(kwargs.keys()))`
- **Cache value**: A template of which parameters to extract
- **Fast path**: On cache hit, extract arguments directly using the template (~1 µs)
- **Slow path**: First call computes full binding and stores template (~2 µs)

This approach preserves **full Dependency Injection functionality** - callbacks still receive correctly filtered arguments (`source`, `target`, etc.).

## Performance

When measuring `bind_expected()` in isolation:
- **Cached**: 0.86 µs/call
- **Uncached**: 2.12 µs/call
- **Improvement**: ~59%

This is consistent with the ~30% end-to-end improvement reported in #548, as binding is one of several components in a full transition.

## Testing

All existing tests pass (328 passed, 9 xfailed).

Fixes #548

* fix: Ensure `**kwargs` only contains unmatched arguments during signature binding by filtering out named parameters.

* chore: Remove extra empty line in test file.

---------

Co-authored-by: rodrigo.nogueira <rodrigo.nogueira@prf.gov.br>

Author: rodrigobnogueira

docs/authors.md

@@ -10,6 +10,7 @@
 * [Rafael Rêgo](mailto:crafards@gmail.com)
 * [Raphael Schrader](mailto:raphael@schradercloud.de)
 * [João S. O. Bueno](mailto:gwidion@gmail.com)
+* [Rodrigo Nogueira](mailto:rodrigo.b.nogueira@gmail.com)
 
 
 ## Scaffolding

statemachine/signature.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from functools import partial
 from inspect import BoundArguments
 from inspect import Parameter
@@ -6,6 +8,12 @@
 from itertools import chain
 from types import MethodType
 from typing import Any
+from typing import FrozenSet
+from typing import Optional
+from typing import Tuple
+
+BindCacheKey = Tuple[int, FrozenSet[str]]
+BindTemplate = Tuple[Tuple[str, ...], Optional[str]]  # noqa: UP007
 
 
 def _make_key(method):
@@ -44,6 +52,11 @@ def cached_function(cls, method):
 
 class SignatureAdapter(Signature):
     is_coroutine: bool = False
+    _bind_cache: dict[BindCacheKey, BindTemplate]
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._bind_cache = {}
 
     @classmethod
     @signature_cache
@@ -60,19 +73,57 @@ def from_callable(cls, method):
         adapter.is_coroutine = iscoroutinefunction(method)
         return adapter
 
-    def bind_expected(self, *args: Any, **kwargs: Any) -> BoundArguments:  # noqa: C901
+    def bind_expected(self, *args: Any, **kwargs: Any) -> BoundArguments:
+        cache_key: BindCacheKey = (len(args), frozenset(kwargs.keys()))
+        template = self._bind_cache.get(cache_key)
+
+        if template is not None:
+            return self._fast_bind(args, kwargs, template)
+
+        result = self._full_bind(cache_key, *args, **kwargs)
+        return result
+
+    def _fast_bind(
+        self,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        template: BindTemplate,
+    ) -> BoundArguments:
+        param_names, kwargs_param_name = template
+        arguments: dict[str, Any] = {}
+
+        for i, name in enumerate(param_names):
+            if i < len(args):
+                arguments[name] = args[i]
+            else:
+                arguments[name] = kwargs.get(name)
+
+        if kwargs_param_name is not None:
+            matched = set(param_names)
+            arguments[kwargs_param_name] = {k: v for k, v in kwargs.items() if k not in matched}
+
+        return BoundArguments(self, arguments)  # type: ignore[arg-type]
+
+    def _full_bind(  # noqa: C901
+        self,
+        cache_key: BindCacheKey,
+        *args: Any,
+        **kwargs: Any,
+    ) -> BoundArguments:
         """Get a BoundArguments object, that maps the passed `args`
         and `kwargs` to the function's signature.  It avoids to raise `TypeError`
         trying to fill all the required arguments and ignoring the unknown ones.
 
         Adapted from the internal `inspect.Signature._bind`.
         """
-        arguments = {}
+        arguments: dict[str, Any] = {}
+        param_names_used: list[str] = []
 
         parameters = iter(self.parameters.values())
         arg_vals = iter(args)
         parameters_ex: Any = ()
         kwargs_param = None
+        kwargs_param_name: str | None = None
 
         while True:
             # Let's iterate through the positional arguments and corresponding
@@ -140,12 +191,14 @@ def bind_expected(self, *args: Any, **kwargs: Any) -> BoundArguments:  # noqa: C
                         values = [arg_val]
                         values.extend(arg_vals)
                         arguments[param.name] = tuple(values)
+                        param_names_used.append(param.name)
                         break
 
                     if param.name in kwargs and param.kind != Parameter.POSITIONAL_ONLY:
                         arguments[param.name] = kwargs.pop(param.name)
                     else:
                         arguments[param.name] = arg_val
+                    param_names_used.append(param.name)
 
         # Now, we iterate through the remaining parameters to process
         # keyword arguments
@@ -171,14 +224,19 @@ def bind_expected(self, *args: Any, **kwargs: Any) -> BoundArguments:  # noqa: C
                 # arguments.
                 pass
             else:
-                arguments[param_name] = arg_val  #
+                arguments[param_name] = arg_val
+                param_names_used.append(param_name)
 
         if kwargs:
             if kwargs_param is not None:
                 # Process our '**kwargs'-like parameter
-                arguments[kwargs_param.name] = kwargs  # type: ignore [assignment]
+                arguments[kwargs_param.name] = kwargs  # type: ignore[assignment]
+                kwargs_param_name = kwargs_param.name
             else:
                 # 'ignoring we got an unexpected keyword argument'
                 pass
 
-        return BoundArguments(self, arguments)  # type: ignore [arg-type]
+        template: BindTemplate = (tuple(param_names_used), kwargs_param_name)
+        self._bind_cache[cache_key] = template
+
+        return BoundArguments(self, arguments)  # type: ignore[arg-type]

tests/test_signature.py

@@ -3,6 +3,7 @@
 
 import pytest
 from statemachine.dispatcher import callable_method
+from statemachine.signature import SignatureAdapter
 
 
 def single_positional_param(a):
@@ -161,3 +162,37 @@ def test_support_for_partial(self):
 
         assert wrapped_func("A", "B") == ("A", "B", "activated")
         assert wrapped_func.__name__ == positional_and_kw_arguments.__name__
+
+
+def named_and_kwargs(source, **kwargs):
+    return source, kwargs
+
+
+class TestCachedBindExpected:
+    """Tests that exercise the cache fast-path by calling the same
+    wrapped function twice with the same argument shape."""
+
+    def setup_method(self):
+        SignatureAdapter.from_callable.clear_cache()
+
+    def test_named_param_not_leaked_into_kwargs(self):
+        """Named params should not appear in the **kwargs dict on cache hit."""
+        wrapped = callable_method(named_and_kwargs)
+
+        # 1st call: cache miss -> _full_bind
+        result1 = wrapped(source="A", target="B", event="go")
+        assert result1 == ("A", {"target": "B", "event": "go"})
+
+        # 2nd call: cache hit -> _fast_bind
+        result2 = wrapped(source="X", target="Y", event="stop")
+        assert result2 == ("X", {"target": "Y", "event": "stop"})
+
+    def test_kwargs_only_receives_unmatched_keys_with_positional(self):
+        """When mixing positional and keyword args with **kwargs."""
+        wrapped = callable_method(named_and_kwargs)
+
+        result1 = wrapped("A", target="B")
+        assert result1 == ("A", {"target": "B"})
+
+        result2 = wrapped("X", target="Y")
+        assert result2 == ("X", {"target": "Y"})