fix(model): let type checkers see the db helpers instead of their stand-ins

[benedikt-bartscher]

reflex.model defines its database helpers only when the db extra is installed (if find_spec("sqlalchemy"): and two more blocks like it), and binds stand-ins that point at the extra otherwise. pyright takes the definitions from the if branch (the else assignments carry # pyright: ignore), but ty unions both branches, so every helper came out unioned with its stand-in:

import reflex as rx
from reflex.model import ModelRegistry

rx.session()  # ty: Session | Unknown
ModelRegistry.register(Base)  # ty: Attribute `register` is not defined on `<class '_ClassThatErrorsOnInit'>` in union `<class 'ModelRegistry'> | <class '_ClassThatErrorsOnInit'>`

The three conditions are now TYPE_CHECKING or ..., so checkers see the real definitions, as if the extra were installed. At runtime TYPE_CHECKING is false and the conditions are unchanged.

tests/type_checking/model.py asserts the types of ModelRegistry.get_metadata(), get_engine(), sqla_session(), migrate(), rx.session() and rx.asession(); under ty it fails with 6 errors before this change. The model unit tests and pyright over all files pass.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge.

Summary

This PR makes type checkers see the database-helper definitions in reflex.model while leaving runtime dependency checks unchanged.

• Adds type assertions for the public database helpers.
• Adds a bug-fix news fragment.

_{Reviews (4) · Last reviewed commit: "Merge branch 'main' into model-db-symbol..." · Reviewed by Greptile}

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}

[codspeed]

Merging this PR will improve performance by 5.61%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
✅ 149 untouched benchmarks
⏩ 18 skipped benchmarks¹

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	test_hydration_metadata[20]	220.5 µs	208.8 µs	+5.61%

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing benedikt-bartscher:model-db-symbols-type-checking (d0f4130) with main (deea1c3)}

Footnotes

1. 18 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. ↩