Skip to content

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

Merged
FarhanAliRaza merged 4 commits into
mainfrom
fix/event-callback-pyright-typing
Nov 11, 2026
Merged

FarhanAliRaza merged 4 commits into
mainfrom
fix/event-callback-pyright-typing

Conversation

@masenf

@masenf masenf commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

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, f5bd795. 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: fix(event): type rx.event handlers as EventCallback under mypy #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, fix(event): type rx.event handlers as EventCallback under mypy #7715's goal.
  • The non-generic re-exports keep TypeAlias, so mypy still accepts rx.event.EventSpec, fix(event): type rx.event handlers as EventCallback under mypy #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

View guided diff Turn on auto-fix

A second @rx.event on a handler crashed at class creation (FINDING-001
of the 0.11.0a1 pre-release testing, e.g. reflex-examples overkey):
the decorator wrapped the inner EventHandler in another one, or failed
its background check or frozen-dataclass setattr first. It now unwraps
the handler and decorates its function again, silently: the markers
accumulate on the function (background/supersedes if either decorator
set them) and the outer decorator's event actions win where both set
one. A repeated decorator on a decentralized handler re-registers it
under the name it already has.

A @staticmethod or @classmethod stacked above @rx.event on a state
returned an EventSpec instead of calling the function (FINDING-016).
The state (and a state copying it from a mixin) now restores the plain
method and warns like @rx.event below them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
@masenf
masenf requested a review from a team as a code owner November 11, 2026 09:09
@masenf masenf added this to the v0.11.0 milestone Nov 11, 2026
@masenf masenf added the on deck PRs lined up to review / merge next label Nov 11, 2026
masenf pushed a commit that referenced this pull request Nov 11, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
@greptile-apps

greptile-apps Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no new actionable issues were found.

Summary

Restores argument types for bare @rx.event handlers under pyright before Python 3.14.

  • Stacked @rx.event decorators register one handler with merged options.
  • Static and class methods stay callable when @rx.event is stacked beneath them.
  • Event handler annotations keep their generic types across Python versions.

No new actionable issues were found. Checks in this review were source-based; tests were not run.

Reviews (4) · Last reviewed commit: "Re-import the generic rx.event re-export..." · Reviewed by Greptile

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 10 files

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

@codspeed

codspeed Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Merging this PR will degrade performance by 6.76%

2 warnings

⚠️ 9 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚠️ 2 benchmarks with a significant change ran on different hardware

Their base and head results were measured on machines with a different CPU, core count or memory, so the changes might not come from the code. Run base and head on the same runner type.

Learn more about Macro Runners

See affected benchmarks

❌ 2 regressed benchmarks
✅ 149 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Benchmark BASE HEAD Efficiency
❌ test_state_collection_assignment[1000] 10.9 ms 11.9 ms -7.88%
❌ test_route_matching[100] 47.7 µs 50.6 µs -5.63%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing fix/event-callback-pyright-typing (c1acfab) with main (34f8c3c)

Open in CodSpeed

….event

Review follow-up. An outer decorator's explicit False or 0 action now
overrides the inner decorator's value (e.g. prevent_default=False over
prevent_default=True); a single @rx.event whose actions are all False
or 0 still carries none, so its compiled output is unchanged. A second
@rx.event on a decentralized handler of a module named like __main__
no longer trips the private-name check on the "_main___" name its
registration gave it. The tests now cover a mixin's repeated handler
and count each staticmethod/classmethod warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
pyright on Python 3.11-3.13 typed every bare @rx.event handler as
EventCallback[*tuple[Unknown, ...]] (FINDING-007 of the 0.11.0a1
pre-release testing): the EventNamespace re-export of EventCallback
shadowed the module class in the __new__ overload's return annotation,
and 3.14's deferred annotations hid it. The annotations now use a
module-level alias.

pyright also read every explicit TypeAlias re-export of a generic in
the class body as already specialized, rejecting annotations such as
rx.event.EventCallback[int] on every Python version. The generic
re-exports (EventCallback, LambdaEventCallback, IdentityEventReturn,
EventType, LAMBDA_OR_STATE, IndividualEventType) are plain assignments
again, as in 0.10.1; the non-generic ones keep TypeAlias so mypy still
accepts rx.event.EventSpec, and mypy still types handlers as
EventCallback through the module-level alias.

pre-commit now runs pyright over tests/type_checking under Python 3.11
and 3.14 regardless of the running interpreter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
@masenf
masenf force-pushed the fix/event-callback-pyright-typing branch from f5bd795 to d34b69c Compare November 11, 2026 09:24
@masenf

masenf commented Nov 11, 2026

Copy link
Copy Markdown
Collaborator Author

On CodSpeed's test_state_access[read_cached_computed] (-14.8%) and [write_inherited] (-7.5%): I measured locally and found no delta, so I read these as hardware noise. CodSpeed itself flags both as measured on different hardware.

Code path. Neither PR touches state access. #7807's runtime changes run only at class or decoration time:

  • the unwrap and action merge in EventNamespace.__new__.wrapper;
  • _method_above_handler in BaseState.__init_subclass__ and _bind_mixin_members.

This PR's own commit only changes type-checker annotations: re-export assignments and a module-level _EventCallback alias. Nothing changes in __getattribute__, __setattr__ or the computed-var path. #7807 carries all of the runtime change, and its CodSpeed report shows no test_state_access regression.

Local numbers. uv run pytest tests/benchmarks/test_state_access.py -k "read_cached_computed or write_inherited" --benchmark-min-rounds=200, interleaved main → #7807 → #7810, 4 rounds on one machine. Times in ms:

benchmark main (2d71015) #7807 (d502726) #7810 (d34b69c)
read_cached_computed, best min 2.270 2.224 2.304
read_cached_computed, medians 2.68–2.87 2.65–3.87 2.70–5.12
write_inherited, best min 9.902 9.811 10.021
write_inherited, medians 12.6–19.6 11.7–15.8 11.6–15.2

The best minimums are within ±2% of main. The medians spread widely within each column, so they cannot show a trend.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi


Generated by Claude Code

masenf pushed a commit that referenced this pull request Nov 11, 2026
…runs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
A plain class-body assignment is a variable to mypy, so
rx.event.EventCallback[int] and the other generic re-exports failed with
valid-type. A class-body `from reflex_base.event import X as X` binds the
class itself: pyright, mypy and ty all accept the subscripted annotation.
EventCallback in the class body is then the class again, so the
module-level _EventCallback workaround goes away.
masenf pushed a commit that referenced this pull request Nov 11, 2026
@FarhanAliRaza
FarhanAliRaza merged commit b95fbf5 into main Nov 11, 2026
167 of 168 checks passed
@FarhanAliRaza
FarhanAliRaza deleted the fix/event-callback-pyright-typing branch November 11, 2026 18:25
masenf added a commit that referenced this pull request Nov 11, 2026
* Merge a repeated @rx.event; restore staticmethod/classmethod above it

A second @rx.event on a handler crashed at class creation (FINDING-001
of the 0.11.0a1 pre-release testing, e.g. reflex-examples overkey):
the decorator wrapped the inner EventHandler in another one, or failed
its background check or frozen-dataclass setattr first. It now unwraps
the handler and decorates its function again, silently: the markers
accumulate on the function (background/supersedes if either decorator
set them) and the outer decorator's event actions win where both set
one. A repeated decorator on a decentralized handler re-registers it
under the name it already has.

A @staticmethod or @classmethod stacked above @rx.event on a state
returned an EventSpec instead of calling the function (FINDING-016).
The state (and a state copying it from a mixin) now restores the plain
method and warns like @rx.event below them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi

* Honor an outer False/0 action and __main__ handlers on a repeated @rx.event

Review follow-up. An outer decorator's explicit False or 0 action now
overrides the inner decorator's value (e.g. prevent_default=False over
prevent_default=True); a single @rx.event whose actions are all False
or 0 still carries none, so its compiled output is unchanged. A second
@rx.event on a decentralized handler of a module named like __main__
no longer trips the private-name check on the "_main___" name its
registration gave it. The tests now cover a mixin's repeated handler
and count each staticmethod/classmethod warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi

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

pyright on Python 3.11-3.13 typed every bare @rx.event handler as
EventCallback[*tuple[Unknown, ...]] (FINDING-007 of the 0.11.0a1
pre-release testing): the EventNamespace re-export of EventCallback
shadowed the module class in the __new__ overload's return annotation,
and 3.14's deferred annotations hid it. The annotations now use a
module-level alias.

pyright also read every explicit TypeAlias re-export of a generic in
the class body as already specialized, rejecting annotations such as
rx.event.EventCallback[int] on every Python version. The generic
re-exports (EventCallback, LambdaEventCallback, IdentityEventReturn,
EventType, LAMBDA_OR_STATE, IndividualEventType) are plain assignments
again, as in 0.10.1; the non-generic ones keep TypeAlias so mypy still
accepts rx.event.EventSpec, and mypy still types handlers as
EventCallback through the module-level alias.

pre-commit now runs pyright over tests/type_checking under Python 3.11
and 3.14 regardless of the running interpreter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi

* Re-import the generic rx.event re-exports so mypy accepts them

A plain class-body assignment is a variable to mypy, so
rx.event.EventCallback[int] and the other generic re-exports failed with
valid-type. A class-body `from reflex_base.event import X as X` binds the
class itself: pyright, mypy and ty all accept the subscripted annotation.
EventCallback in the class body is then the class again, so the
module-level _EventCallback workaround goes away.

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Farhan <www.mfarvirus@gmail.com>
(cherry picked from commit b95fbf5)
masenf pushed a commit that referenced this pull request Nov 11, 2026
…maining commits

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
@masenf masenf added the release-train Issues found during agentic /prerelease-testing fanout, not necessarily validated bugs. label Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

on deck PRs lined up to review / merge next release-train Issues found during agentic /prerelease-testing fanout, not necessarily validated bugs.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants