Keyword arguments are not supported for Events

[bertbarabas]

Describe the bug
When yielding a server event with a keyword argument from a server event, the type checker complains with:

Unexpected keyword argument `tries` in function `reflex_base.event.EventCallback.__call__`

To Reproduce
Just paste the code below into your code editor with type checking enabled and note the underlined keyword as shown in the screen shot.

• Code:

import reflex as rx


class MyState(rx.State):
    @rx.event
    def do_something(self, tries=1):
        # yield something to client
        if tries > 0:
            yield MyState.do_something(tries=tries - 1)

Expected behavior
There should not be any type check errors

Screenshots

Specifics:

• Python Version: 3.14
• Reflex Version: 0.9.2
• OS: Ubuntu

[linear]

ENG-9493

[masenf]

Took a stab at this on the branch claude/fix-eventcallback-typing-GXfrc (commits d24c92f and 4944e4d). Not opening a PR yet — flagging the design trade-offs here first.

Approach

Made EventCallback generic over two parameters:

• Unpack[P] (TypeVarTuple) — the positional shape used by EventType[int, str]-style aliases, preserved so LAMBDA_OR_STATE and arity checks at assignment sites keep working.
• P_spec (ParamSpec) — the full signature of the wrapped callable, so __call__ accepts positional or keyword arguments and type-checks them against the underlying signature.

class EventCallback(Generic[Unpack[P], P_spec], EventActionsMixin):
    def __init__(self, func: Callable[Concatenate[Any, P_spec], Any]): ...

@rx.event has per-arity overloads (0–4 args) that extract the TVT precisely, plus a Concatenate[BASE_STATE, P_spec] catch-all for 5+ args. LAMBDA_OR_STATE is now LambdaEventCallback[Unpack[ARGS]] | EventCallback[Unpack[ARGS], ...].

__call__ has overloads in this order:

1. Strict ParamSpec: (*args: P_spec.args, **kwargs: P_spec.kwargs) — full type checking when P_spec is precise.
2. Per-arity positional overloads with V | Var[V] accepting **kwargs: Var[Any] — preserves the existing Var-positional flexibility and lets callers pass Var-wrapped kwargs without losing positional adherence.
3. Catch-all (*args: Any, **kwargs: Any) impl.

What now type-checks

The exact code from the bug report works:

class MyState(rx.State):
    @rx.event
    def do_something(self, tries=1):
        if tries > 0:
            yield MyState.do_something(tries=tries - 1)  # ✓

Other cases that work:

Call	Overload used
MyState.do_something(2)	strict
MyState.do_something(tries=2)	strict (or per-arity wildcard, see caveat)
MyState.do_something(Var(2))	per-arity V | Var[V]
MyState.do_something(tries=Var(2))	per-arity **kwargs: Var[Any]
EventType[()] = MyState.takes_str (arity mismatch)	rejected ✓

Trade-off / caveat

There is no Python-typing primitive that maps T → T | Var[T] over each parameter of a ParamSpec, so I had to pick: extract the TVT precisely (for arity checks) or extract P_spec precisely (for strict kwarg name/type checks). The per-arity decorator overloads optimise for the former, which means:

• For 0–4 arg handlers, P_spec becomes ... and the strict overload accepts any kwarg shape — so MyState.do_something(wrong_name=2) or tries="oops" slip through type-checking. They'll still fail at runtime in EventHandler.__call__.
• For 5+ arg handlers, P_spec is extracted precisely and both name and type are checked.
• Arity-mismatch checks at EventType[...] assignment sites keep working in both cases.

Possible next steps if stricter kwarg checking matters more than EventType arity checking:

1. Drop the per-arity decorator overloads and always go through Concatenate[BASE_STATE, P_spec], accepting that EventType[()] = MyState.takes_str would no longer be flagged at assignment time.
2. Require users to opt into Var[T] in handler signatures (def f(self, email: str | Var[str])) and lose the implicit T | Var[T] flexibility everywhere.

Happy to take either direction — wanted to capture the design space before turning it into a PR.

---

Generated by Claude Code