Type bare @rx.event handlers under pyright before Python 3.14
Merged
MA
10d ago+355+355+012345678901234567890123456789-53-53-01234567890123456789
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.eventhandler asEventCallback[*tuple[Unknown, ...]]. On 0.10.1 it wasEventCallback[int]. Wrong-type calls are no longer reported, and a# pyright: strictapp goes from 4 to 18 errors.@rx.event()with parentheses is not affected.- Cause: #7715 added
EventCallback: TypeAlias = EventCallbackinsideclass 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.
- Cause: #7715 added
- Side finding: on every Python version, pyright reports annotations such as
rx.event.EventCallback[int]as "already specialized". It does this for every explicitTypeAliasre-export of a generic in that class body, sorx.event.LambdaEventCallback[...],rx.event.IdentityEventReturn[...]andrx.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_STATEandIndividualEventType. An import binds the class itself rather than declaring an alias, so pyright, mypy and ty all acceptrx.event.EventCallback[int]. In the class bodyEventCallbackis the class again, so the overload's-> EventCallback[*P]types handlers asEventCallback[int]under pyright 3.11–3.14 and mypy, #7715's goal. - The non-generic re-exports keep
TypeAlias, so mypy still acceptsrx.event.EventSpec, #7715's other goal. Runtime behaviour does not change: eachrx.event.Xis thereflex_base.event.Xobject. .pre-commit-config.yamlgets two hooks,pyright-type-checking-3.11andpyright-type-checking-3.14. They runpyright --pythonversion <v> tests/type_checkingalways, whatever the running interpreter. The pre-commit workflow already runspre-commit run --all-files, so no workflow, gate or ruleset change is needed.tests/type_checking/README.mdis updated to match.tests/type_checking/event.pygainsassert_typechecks 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_namereceivedEventCallback[*tuple[Unknown, ...]]. - Under every version: the namespace annotations failed with "already specialized".
After the fix:
- Both hooks pass, and pyright with
--pythonversion3.11, 3.12, 3.13 and 3.14 overtests/type_checkingreports 0 errors.typasses too. - In a probe app, pyright on 3.12 and 3.14 reveals
S.bareasEventCallback[int]and reportsS.bare("wrong")as an error.rx.event.EventCallback[int]is accepted as an annotation. - In the same probe, mypy 2.4.1 reveals
S.bareasEventCallback[int], catchesS.bare("wrong"), and acceptsrx.event.EventSpecas an annotation. - mypy 2.4.1 accepts all six generic re-exports subscripted through
rx.event, andtests/type_checking/event.pyis clean under it. With plain class-body assignments it reported 7 errors there (valid-typeandassert-type). uv run pyright reflex tests: 0 errors.ruff checkandruff formatare 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.pywas 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
TypeAliasto a bare generic as already specialized, at module scope too; - mypy reads a plain class-body assignment as a variable (its docs ask for
TypeAliasin a class body); - a
TypeAliasTypeunderTYPE_CHECKINGtrips a mypy bug withTypeVarTuple.
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.
- pyright reads an explicit
- 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