Resolve PEP 695 type aliases in _isinstance and typehint_issubclass

[masenf]

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?

Defect

Found in 0.9.9a1 pre-release testing as FINDING-002 (HIGH) and FINDING-006 (MEDIUM). PR #6944 added resolve_type_alias() to reflex_base/utils/types.py but wired it only into Var.guess_type, so state vars annotated with a PEP 695 alias (type Key = Literal["a", "b"], or the typing_extensions.TypeAliasType backport that 3.10/3.11 users hit) compiled while every runtime path that re-checks the raw annotation still choked on the TypeAliasType:

• FINDING-002: State.__setattr__ validates assignments through _isinstance(), which fell through to the bare isinstance() call and raised TypeError: isinstance() arg 2 must be a type, a tuple of types, or a union on every assignment to an alias-annotated var. The guard was designed to only logger.error a mismatch, but the TypeError escaped and aborted event processing — alias vars compiled but every mutating event handler died.
• FINDING-006: an event handler whose argument is alias-annotated, passed uncalled to an event trigger (rx.input(on_change=S.choose)), crashed page compile: typehint_issubclass() reached the bare issubclass() for a plain alias (TypeError: Could not compare types <class 'str'> and Key) and failed the origin comparison for a subscripted alias (Pair[str, str]), escalating what should at most be a warning into a fatal EventHandlerArgTypeMismatchError.

Fix

Resolve TypeAliasType at the entry of _isinstance (the annotation operand) and typehint_issubclass (both operands), reusing the existing resolve_type_alias() helper, which already handles parameterized aliases (Items[str]) and aliases nested in unions (Key | None). Nested annotations (e.g. an alias inside list[...]) are covered by both functions' per-argument recursion resolving at each entry. Alias-annotated vars and handler arguments now behave exactly like their resolved annotations at runtime; the resolution is a no-op fast path for non-alias types. News fragment added in packages/reflex-base/news/.

Test plan

Regression tests written first and shown to fail on unfixed main with exactly the reported errors:

• tests/units/reflex_base/utils/test_types.py::test_isinstance_resolves_type_alias and ::test_typehint_issubclass_resolves_type_alias — plain alias, Literal alias, parameterized generic alias, and alias | None, parameterized over the typing_extensions backport and (on 3.12+) the native typing.TypeAliasType that the type statement produces.
• tests/units/test_state.py::test_setattr_alias_annotated_var — a state with all four alias-annotated var shapes assigns them via an event handler; also pins that a mismatched value is logged, not raised.

Verified locally: uv run pytest tests/units/utils/test_types.py tests/units/reflex_base/utils/test_types.py tests/units/reflex_base/vars/test_base.py tests/units/test_state.py tests/units/test_event.py tests/units/components tests/units/test_app.py (4600+ passed), uv run ruff check ., uv run ruff format ., uv run pyright reflex tests (0 errors), uv run pyright packages/reflex-base (0 errors, 1 pre-existing warning in an untouched file). Both pre-release repro scripts (repro_alias_setattr.py, repro_alias_event_arg.py, Python 3.14 native type statements) now pass, and a parameterized-alias on_submit handler behaves identically to a plain dict[str, str] annotation.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EMjBXPozsNeQNSBZecNH8x

---

Generated by Claude Code

[greptile-apps]

Greptile Summary

The PR resolves PEP 695 and typing_extensions type aliases during runtime instance and type-hint subclass checks.

• Adds lazy alias resolution for bare, parameterized, union-wrapped, and nested aliases.
• Adds regression coverage for state assignment and event-handler argument validation.
• Documents the runtime alias fix in a news fragment.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/utils/types.py	Adds lazy TypeAliasType resolution to _isinstance and typehint_issubclass while preserving existing non-alias paths.
tests/units/reflex_base/utils/test_types.py	Adds direct coverage for bare, literal, generic, optional, and union-valued aliases across both runtime type helpers.
tests/units/test_event.py	Adds event-handler regression coverage for alias-annotated arguments and genuine mismatches.
tests/units/test_state.py	Adds state-assignment regression coverage for alias-annotated variables and mismatch logging.
packages/reflex-base/news/+pep695-alias-runtime.bugfix.md	Describes the resolved state-assignment and event-compilation failures.

_{Reviews (5): Last reviewed commit: "Merge branch 'main' into claude/rel-fix-..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 32 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing claude/rel-fix-pep695-alias-runtime (c56a9f8) with main (4bc9678)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[cubic-dev-ai]

No issues found across 4 files

_{Re-trigger cubic}

[benedikt-bartscher]

@masenf with #6862 merged in this (#6988), codspeed is green: codspeed

[FarhanAliRaza]

Validated end to end in a real app (Python 3.14 native type statements: plain, Literal, Items[T], Pair[K, V], Key | None): alias-annotated var assignment works, uncalled alias-annotated handlers on on_change/on_submit compile and fire, mismatches log instead of raise, plain vars unaffected. Regression tests fail without the source change. One perf concern inline.

[masenf]

@benedikt-bartscher awesome thanks for that. will merge yours in and rebase this one. 0.9.9 is getting close 🤞

[benedikt-bartscher]

I guess we can improve performance for the new benchmarks a bit

[masenf]

I guess we can improve performance for the new benchmarks a bit

yeah, that unconditional type alias unpacking is more expensive than i realized. probably need to cache it and see if that makes a difference

[masenf]

Pushed e688d7d taking a slightly different route than caching: the unconditional resolve_type_alias() at the entry of _isinstance/typehint_issubclass is gone entirely — resolution now happens only at the exact points where an alias would be opaque (a zero-cost try/except TypeError around the final isinstance/issubclass mirroring safe_issubclass, a guard before union decomposition so an alias-of-a-union keeps union semantics, and the union branch of resolve_type_alias no longer allocates unless a member actually resolved). Local numbers vs main: _isinstance('x', str|None) 1.61µs → 4.78µs on the previous head → 1.60µs now; typehint_issubclass(str, str|None) 1.81 → 5.98 → 1.89µs; test_process_event mean back inside main's noise band. All alias-semantics tests still pass (plain/Literal/parameterized, alias|None, native + typing_extensions), plus new alias-of-union coverage and a trigger-path regression test for the uncalled-handler crash. CodSpeed should confirm on this head; caching remains an option if it still flags anything.

---

Generated by Claude Code

[masenf]

i wouldn't be surprised if that last remaining codspeed issue is really just a fluke. 4% regression on different hardware than the baseline, and we have our threshold set at 3%

[masenf]

CodSpeed status on this PR, for whoever merges: the genuine regression is fixed and the remaining flag looks like environment noise.

• Head 7e845d2 (unconditional resolution): 8 regressed benchmarks, -33.7% — real, root-caused, fixed in e688d7d.
• Head e688d7d: only test_isinstance_container[list_dict] at -7.58% — also real (the per-call isinstance(origin, TypeAliasTypes) probe), fixed in 758bf18 by moving the check into the final fallback's TypeError handler, so alias-free checks pay nothing. Interleaved local A/B on that benchmark: parity with main (8.4 vs 8.45ms; previous head 9.07ms).
• Head 758bf18: list_dict is green, but CodSpeed now flags a different benchmark, test_get_all_imports[_complicated_page] at -4.47%, with its own "different runtime environments detected" warning. Interleaved local timeit A/B of page._get_all_imports() on the same _complicated_page fixture shows identity between this head and main after warm-up (0.4617 vs 0.4647 ms; 0.4567 vs 0.4579 ms) — and this diff only touches _isinstance/typehint_issubclass/resolve_type_alias, none of which are on the import-collection path.

Each successive flag has been a different benchmark under a cross-environment comparison, so I'm not pushing further speculative changes. If you agree it's noise, acknowledging on CodSpeed (or a re-run against a same-environment baseline) should clear the check.

---

Generated by Claude Code

[benedikt-bartscher]

i wouldn't be surprised if that last remaining codspeed issue is really just a fluke. 4% regression on different hardware than the baseline, and we have our threshold set at 3%

maybe #6993 helps a tiny bit