Lazy Export Mechanism
Relevant source files
The following files were used as context for generating this wiki page:
The Lazy Export Mechanism in flext-observability is a performance-oriented architecture designed to defer the loading of heavy modules until they are explicitly accessed. By utilizing a lazy import map, the package minimizes startup overhead and memory consumption, which is critical for a high-performance observability platform.
This mechanism is implemented through a series of auto-generated export maps and a centralized installation process within the package's entry point. It ensures that the public API remains consistent while the underlying implementation is loaded on demand.
Sources: src/flext_observability/init.py:1-68, src/flext_observability/_exports.py:1-35
Architecture and Components
The mechanism is structured into three distinct layers: the Import Maps, the Merged Registry, and the Lazy Installer.
Lazy Import Maps
The implementation details are partitioned into multiple "lazy part" files. This partitioning allows for modular management of the import paths and their associated exported names. Each part uses build_lazy_import_map from the flext_core.lazy library to define a dictionary where keys are relative module paths and values are tuples of names to be exported.
- Part 01: Contains core services (Context, Custom Metrics, Health, Monitoring), API facades, and type definitions.
- Part 02: Contains utility aliases and core extensions.
Sources: src/flext_observability/_exports_lazy_part_01.py:8-58, src/flext_observability/_exports_lazy_part_02.py:8-14
Merged Registry (_exports.py)
The _exports.py file acts as a consolidator. It merges the various lazy import parts into a single FLEXT_OBSERVABILITY_LAZY_IMPORTS object using merge_lazy_imports. This stage also includes a blacklist (exclude_names) to prevent internal utilities, test hooks (such as pytest_* functions), and standard library loggers from being lazily exported.
Sources: src/flext_observability/_exports.py:14-35
Lazy Export Flow
The following diagram illustrates how the lazy exports are aggregated and finally installed into the package namespace.
The diagram shows the aggregation of individual lazy maps and exclusion lists into a final map that is installed at the package root.
Sources: src/flext_observability/_exports.py:14-35, src/flext_observability/init.py:60-65
Implementation Details
Module Mapping
The mapping connects internal relative paths to public-facing identifiers. This allows the user to access components like flext_monitor_function directly from the root package without triggering an immediate import of the entire monitoring service.
| Relative Module Path | Exported Names | Public Facade / Alias |
|---|---|---|
.api | FlextObservability, observability | Primary API entry points |
.constants | FlextObservabilityConstants | c |
.models | FlextObservabilityModels | m |
.protocols | FlextObservabilityProtocols | p |
.typings | FlextObservabilityTypes | t |
.services.monitoring | FlextObservabilityMonitor, flext_monitor_function | Monitoring utilities |
Sources: src/flext_observability/_exports_lazy_part_01.py:10-48, src/flext_observability/init.py:31-57
Package Initialization
In src/flext_observability/__init__.py, the install_lazy_exports function is called. It takes the current module name (__name__), the global namespace (globals()), the merged lazy imports, and a explicit list of _PUBLIC_EXPORTS.
# src/flext_observability/__init__.py:60-65
install_lazy_exports(
__name__,
globals(),
_LAZY_IMPORTS,
public_exports=_PUBLIC_EXPORTS,
)
Sources: src/flext_observability/init.py:60-65
Application in Testing and Submodules
The lazy mechanism is not restricted to the main package; it is also applied to the tests and tests.integration packages to maintain consistency and efficiency during test discovery.
Test Registry Integration
The tests/__init__.py file uses merge_lazy_imports to combine local test utilities, base classes, and submodule lazy maps (unit and integration) while excluding pytest lifecycle hooks.
The sequence diagram demonstrates how the test runner accesses submodules without pre-loading the entire test suite.
Sources: tests/init.py:75-125, tests/integration/init.py:7-34
Summary of Exclusions
To ensure a clean public namespace, several internal and lifecycle functions are explicitly excluded from the lazy export mechanism.
| Exclusion Category | Example Names |
|---|---|
| Lazy Internal Utilities | install_lazy_exports, lazy_getattr, merge_lazy_imports |
| Output/Logging | logger, output, output_reporting |
| Pytest Hooks | pytest_configure, pytest_sessionstart, pytest_terminal_summary |
Sources: src/flext_observability/_exports.py:18-32, tests/init.py:110-123
The Lazy Export Mechanism serves as the backbone for the package's initialization logic, ensuring that flext-observability remains lightweight and responsive by only loading components as they are required by the application or test environment.