Type bare @rx.event handlers under pyright before Python 3.14

Merged
MA
10d ago
+355-53

Stacked on #7807. This branch is cut from fix/repeated-rx-event, so until #7807 lands the diff also shows that PR's commit. This PR's own change is the last commit, f5bd795e1. The two do not depend on each other; their hunks in reflex_base/event/__init__.py are separate.

All Submissions:

  • Have you followed the guidelines stated in CONTRIBUTING.md file?
  • Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

  • Bug fix (non-breaking change which fixes an issue)

Changes To Core Features:

  • Have you added an explanation of what your changes do and why you'd like us to include them?
  • Have you written new tests for your core changes, as applicable?
  • Have you successfully ran tests with your changes locally?

This is a release fix-up for FINDING-007 (MEDIUM, regression) from the reflex 0.11.0a1 pre-release testing (artifacts on branch claude/vibrant-pasteur-3921g3, prerelease-testing/runs/2026-11-11-v0.11.0a1/).

Defect

  • On Python 3.11–3.13, pyright types every bare @rx.event handler as EventCallback[*tuple[Unknown, ...]]. On 0.10.1 it was EventCallback[int]. Wrong-type calls are no longer reported, and a # pyright: strict app goes from 4 to 18 errors. @rx.event() with parentheses is not affected.
    • Cause: #7715 added EventCallback: TypeAlias = EventCallback inside class EventNamespace, which shadows the class in the __new__ overload's -> EventCallback[*P].
    • CI did not catch it: Python 3.14's deferred annotations hide the bug, and pre-commit's pyright uses the 3.14 interpreter.
  • Side finding: on every Python version, pyright reports annotations such as rx.event.EventCallback[int] as "already specialized". It does this for every explicit TypeAlias re-export of a generic in that class body, so rx.event.LambdaEventCallback[...], rx.event.IdentityEventReturn[...] and rx.event.EventType[...] fail too. All of them were clean on 0.10.1.

Fix

  • The generic re-exports are class-body re-imports, from reflex_base.event import X as X: EventCallback, LambdaEventCallback, IdentityEventReturn, EventType, LAMBDA_OR_STATE and IndividualEventType. An import binds the class itself rather than declaring an alias, so pyright, mypy and ty all accept rx.event.EventCallback[int]. In the class body EventCallback is the class again, so the overload's -> EventCallback[*P] types handlers as EventCallback[int] under pyright 3.11–3.14 and mypy, #7715's goal.
  • The non-generic re-exports keep TypeAlias, so mypy still accepts rx.event.EventSpec, #7715's other goal. Runtime behaviour does not change: each rx.event.X is the reflex_base.event.X object.
  • .pre-commit-config.yaml gets two hooks, pyright-type-checking-3.11 and pyright-type-checking-3.14. They run pyright --pythonversion <v> tests/type_checking always, whatever the running interpreter. The pre-commit workflow already runs pre-commit run --all-files, so no workflow, gate or ruleset change is needed. tests/type_checking/README.md is updated to match.
  • tests/type_checking/event.py gains assert_type checks for annotations made through the namespace (event.EventCallback[str], event.LambdaEventCallback[str], event.IdentityEventReturn[int], event.EventType[str], event.EventSpec).

Test plan

Failing before (source fix reverted, new tests and hooks kept):

pyright type_checking (Python 3.11)......Failed   27 errors
pyright type_checking (Python 3.14)......Failed   12 errors
  • Under 3.11–3.13: the existing assert_types on _HandlerState.* and _State.set_name received EventCallback[*tuple[Unknown, ...]].
  • Under every version: the namespace annotations failed with "already specialized".

After the fix:

  • Both hooks pass, and pyright with --pythonversion 3.11, 3.12, 3.13 and 3.14 over tests/type_checking reports 0 errors. ty passes too.
  • In a probe app, pyright on 3.12 and 3.14 reveals S.bare as EventCallback[int] and reports S.bare("wrong") as an error. rx.event.EventCallback[int] is accepted as an annotation.
  • In the same probe, mypy 2.4.1 reveals S.bare as EventCallback[int], catches S.bare("wrong"), and accepts rx.event.EventSpec as an annotation.
  • mypy 2.4.1 accepts all six generic re-exports subscripted through rx.event, and tests/type_checking/event.py is clean under it. With plain class-body assignments it reported 7 errors there (valid-type and assert-type).
  • uv run pyright reflex tests: 0 errors. ruff check and ruff format are clean.
  • uv run pytest tests/units --cov --no-cov-on-fail --cov-report=: 15643 passed, 66 skipped, coverage 81.43%. tests/units/reflex_bench/drivers/test_browser.py was excluded because the sandbox has no Chromium for it.

Notes

  • Why a re-import. The other forms of the class-body re-export each fail one checker when subscripted:
    • pyright reads an explicit TypeAlias to a bare generic as already specialized, at module scope too;
    • mypy reads a plain class-body assignment as a variable (its docs ask for TypeAlias in a class body);
    • a TypeAliasType under TYPE_CHECKING trips a mypy bug with TypeVarTuple.
      An import is not an alias declaration, so neither rule applies. It is the explicit re-export idiom (from x import Y as Y) that libraries such as FastAPI use at module scope.
  • The pinned hook uses the 3.11 floor rather than 3.12. The bug shows the same way on 3.11–3.13, and the README already asked for a floor check so that 3.12+ constructs get caught.

Generated by Claude Code