From 0047d7be3f6260c3ed2820a730812af5e28112f8 Mon Sep 17 00:00:00 2001 From: Benedikt Bartscher Date: Sun, 15 Nov 2026 21:33:30 +0100 Subject: [PATCH 1/2] perf(base): import Rich extras and ElementTree lazily on Python 3.15 List them in `__lazy_modules__` (PEP 810), so Python 3.15 imports them the first time they are used. Older Pythons ignore the variable. - reflex_base.utils.console: rich.progress, rich.prompt and rich.table are only used by progress(), ask() and print_table(). rich.console stays eager because the module creates its Console at import time. - reflex_base.plugins.sitemap: xml.etree.ElementTree is only used to render the sitemap. `reflex --help` on 3.15.2 no longer loads these modules (about 6 ms of imports). The new test imports each module in a fresh interpreter and checks which names are still lazy. Co-Authored-By: Claude Opus 5.5 --- .../news/+lazy-modules.performance.md | 1 + .../src/reflex_base/plugins/sitemap.py | 3 + .../src/reflex_base/utils/console.py | 3 + tests/units/test_lazy_modules.py | 61 +++++++++++++++++++ 4 files changed, 68 insertions(+) create mode 100644 packages/reflex-base/news/+lazy-modules.performance.md create mode 100644 tests/units/test_lazy_modules.py diff --git a/packages/reflex-base/news/+lazy-modules.performance.md b/packages/reflex-base/news/+lazy-modules.performance.md new file mode 100644 index 00000000000..b3c93dbe475 --- /dev/null +++ b/packages/reflex-base/news/+lazy-modules.performance.md @@ -0,0 +1 @@ +On Python 3.15 and newer, the console's Rich progress, prompt and table modules and the sitemap plugin's XML module are only imported once they are used (PEP 810 lazy imports), so the `reflex` CLI starts faster. Older Python versions are unaffected. diff --git a/packages/reflex-base/src/reflex_base/plugins/sitemap.py b/packages/reflex-base/src/reflex_base/plugins/sitemap.py index c09f7adde52..edd7a933b47 100644 --- a/packages/reflex-base/src/reflex_base/plugins/sitemap.py +++ b/packages/reflex-base/src/reflex_base/plugins/sitemap.py @@ -1,5 +1,8 @@ """Sitemap plugin for Reflex.""" +# Imported on first use on Python 3.15+ (PEP 810); keep them out of import-time code. +__lazy_modules__ = ["xml.etree.ElementTree"] + import datetime import logging from collections.abc import Sequence diff --git a/packages/reflex-base/src/reflex_base/utils/console.py b/packages/reflex-base/src/reflex_base/utils/console.py index a25d7dbcd7b..5b6a7fa32d8 100644 --- a/packages/reflex-base/src/reflex_base/utils/console.py +++ b/packages/reflex-base/src/reflex_base/utils/console.py @@ -9,6 +9,9 @@ from __future__ import annotations +# Imported on first use on Python 3.15+ (PEP 810); keep them out of import-time code. +__lazy_modules__ = ["rich.progress", "rich.prompt", "rich.table"] + import contextlib import datetime import time diff --git a/tests/units/test_lazy_modules.py b/tests/units/test_lazy_modules.py new file mode 100644 index 00000000000..e7e16f7dd55 --- /dev/null +++ b/tests/units/test_lazy_modules.py @@ -0,0 +1,61 @@ +"""The `__lazy_modules__` declarations keep their imports lazy on Python 3.15+ (PEP 810).""" + +import json +import subprocess +import sys + +import pytest + +pytestmark = pytest.mark.skipif( + sys.version_info < (3, 15), reason="PEP 810 lazy imports need Python 3.15+" +) + +# Lists the names in the module's namespace that are still unresolved lazy imports. +_LIST_LAZY_NAMES = ( + "import importlib, json, sys, types; " + "module = importlib.import_module(sys.argv[1]); " + "print(json.dumps(sorted(name for name, value in vars(module).items() " + "if type(value) is types.LazyImportType)))" +) + + +@pytest.mark.parametrize( + ("module", "lazy_names"), + [ + ( + "reflex_base.plugins.sitemap", + ["Element", "SubElement", "indent", "tostring"], + ), + ( + "reflex_base.utils.console", + [ + "MofNCompleteColumn", + "Progress", + "Prompt", + "Table", + "TaskID", + "TimeElapsedColumn", + ], + ), + ], +) +def test_lazy_modules_are_not_imported_by_the_module_itself( + module: str, lazy_names: list[str] +): + """Importing the module leaves the imports of its `__lazy_modules__` unresolved. + + Each module runs in a fresh interpreter: an import of a module that is + already loaded binds the real object instead of a lazy proxy. + + Args: + module: The module that declares `__lazy_modules__`. + lazy_names: The names its imports of those modules bind. + """ + result = subprocess.run( + [sys.executable, "-c", _LIST_LAZY_NAMES, module], + check=True, + capture_output=True, + text=True, + ) + + assert json.loads(result.stdout) == lazy_names From 559b0258e9df3e0472c59828298e71885764c032 Mon Sep 17 00:00:00 2001 From: Benedikt Bartscher Date: Sun, 15 Nov 2026 21:33:53 +0100 Subject: [PATCH 2/2] perf: defer the compiler, click, packaging and multiprocessing on Python 3.15 List them in `__lazy_modules__` (PEP 810), so Python 3.15 imports them the first time they are used. Older Pythons ignore the variable. - reflex.app: reflex.compiler and reflex.compiler.compiler. Importing reflex.app, creating rx.App() and add_page() don't compile, so the compiler and the 19 modules it pulls in now load when the app is compiled. - reflex.utils.exec: click only parses GRANIAN_RESPAWN_FAILED_WORKERS in run_granian_backend_prod(). - reflex.utils.prerequisites, reflex.utils.js_runtimes: packaging is only used for version checks. - reflex.utils.telemetry: multiprocessing is only used by get_cpu_count(). `reflex.utils` itself is not listed in reflex.app: the same statement imports telemetry_accounting, which imports reflex.istate.shared, and that module registers SharedStateBaseInternal as a substate of State. Co-Authored-By: Claude Opus 5.5 --- news/+lazy-modules.performance.md | 1 + reflex/app.py | 3 +++ reflex/utils/exec.py | 3 +++ reflex/utils/js_runtimes.py | 3 +++ reflex/utils/prerequisites.py | 3 +++ reflex/utils/telemetry.py | 3 +++ tests/units/test_lazy_modules.py | 5 +++++ 7 files changed, 21 insertions(+) create mode 100644 news/+lazy-modules.performance.md diff --git a/news/+lazy-modules.performance.md b/news/+lazy-modules.performance.md new file mode 100644 index 00000000000..f880dc31033 --- /dev/null +++ b/news/+lazy-modules.performance.md @@ -0,0 +1 @@ +On Python 3.15 and newer, importing `reflex.app` no longer loads the compiler, and `click`, `packaging` and `multiprocessing` are only imported once they are used (PEP 810 lazy imports), so apps import faster. Older Python versions are unaffected. diff --git a/reflex/app.py b/reflex/app.py index 718b7e0c4ae..4f52d4da876 100644 --- a/reflex/app.py +++ b/reflex/app.py @@ -2,6 +2,9 @@ from __future__ import annotations +# Imported on first use on Python 3.15+ (PEP 810); keep them out of import-time code. +__lazy_modules__ = ["reflex.compiler", "reflex.compiler.compiler"] + import asyncio import contextlib import copy diff --git a/reflex/utils/exec.py b/reflex/utils/exec.py index 995ad77fafc..1ee0662d184 100644 --- a/reflex/utils/exec.py +++ b/reflex/utils/exec.py @@ -2,6 +2,9 @@ from __future__ import annotations +# Imported on first use on Python 3.15+ (PEP 810); keep them out of import-time code. +__lazy_modules__ = ["click"] + import contextlib import functools import hashlib diff --git a/reflex/utils/js_runtimes.py b/reflex/utils/js_runtimes.py index 535d6ff57ad..29ed3ad9bc4 100644 --- a/reflex/utils/js_runtimes.py +++ b/reflex/utils/js_runtimes.py @@ -1,5 +1,8 @@ """This module provides utilities for managing JavaScript runtimes like Node.js and Bun.""" +# Imported on first use on Python 3.15+ (PEP 810); keep them out of import-time code. +__lazy_modules__ = ["packaging"] + import functools import json import logging diff --git a/reflex/utils/prerequisites.py b/reflex/utils/prerequisites.py index c7e32ac36ab..9892981e9db 100644 --- a/reflex/utils/prerequisites.py +++ b/reflex/utils/prerequisites.py @@ -2,6 +2,9 @@ from __future__ import annotations +# Imported on first use on Python 3.15+ (PEP 810); keep them out of import-time code. +__lazy_modules__ = ["packaging"] + import contextlib import importlib import importlib.metadata diff --git a/reflex/utils/telemetry.py b/reflex/utils/telemetry.py index e669935681c..21678a5a849 100644 --- a/reflex/utils/telemetry.py +++ b/reflex/utils/telemetry.py @@ -1,5 +1,8 @@ """Anonymous telemetry for Reflex.""" +# Imported on first use on Python 3.15+ (PEP 810); keep them out of import-time code. +__lazy_modules__ = ["multiprocessing"] + import dataclasses import importlib.metadata import json diff --git a/tests/units/test_lazy_modules.py b/tests/units/test_lazy_modules.py index e7e16f7dd55..9d1998f14c8 100644 --- a/tests/units/test_lazy_modules.py +++ b/tests/units/test_lazy_modules.py @@ -22,6 +22,11 @@ @pytest.mark.parametrize( ("module", "lazy_names"), [ + ("reflex.app", ["compiler", "readable_name_from_component"]), + ("reflex.utils.exec", ["click"]), + ("reflex.utils.js_runtimes", ["version"]), + ("reflex.utils.prerequisites", ["version"]), + ("reflex.utils.telemetry", ["multiprocessing"]), ( "reflex_base.plugins.sitemap", ["Element", "SubElement", "indent", "tostring"],