Lazy Export & MRO System
Relevant source files
The following files were used as context for generating this wiki page:
The Lazy Export and Method Resolution Order (MRO) system in flext-oracle-wms is a core architectural pattern designed to optimize startup performance and ensure strict adherence to the FLEXT ecosystem's inheritance and integration standards. It utilizes lazy loading mechanisms to defer the importation of heavy modules until they are explicitly accessed, significantly reducing the initial memory footprint and execution time for discovery operations.
This system is central to the project's compliance with FLEXT governance rules, which mandate specific MRO chains for facade classes to ensure consistent behavior across different domain adapters. By using a declarative export map, the library manages complex dependencies between internal modules (like API catalogs and discovery utilities) and external FLEXT core components.
Sources: src/README.md:143-146, README.md:24-28, src/flext_oracle_wms/__init__.py:46-52
Architectural Overview
The architecture relies on a "Public API Gateway" pattern implemented in the package's __init__.py. This gateway uses the flext_core.lazy utility to install exports dynamically. The implementation is split into eager exports (metadata like versioning) and lazy exports (functional logic).
The diagram shows how __init__.py serves as a gatekeeper, immediately exporting metadata while deferring the load of core logic modules until they are requested by a consumer.
Sources: src/flext_oracle_wms/__init__.py:20-63, src/flext_oracle_wms/README.md:23-26
Export Mapping & Lazy Import Logic
The system uses build_lazy_import_map to define the relationship between public-facing aliases and their internal file paths. This mapping is partitioned (e.g., PART_01) to maintain readability and manage large catalogs of internal utilities.
Primary Import Map Components
The import map organizes exports into logical groups that align with the library's infrastructure and discovery capabilities.
| Public Export Group | Internal Path | Key Members |
|---|---|---|
| API | .api | FlextOracleWmsApi, oracle_wms |
| Constants | .constants | FlextOracleWmsConstants, c |
| Models | .models | FlextOracleWmsModels, m |
| Utilities | .utilities | FlextOracleWmsUtilities, u |
| FLEXT Core Aliases | flext_core | d, e, h, r, s, x |
Sources: src/flext_oracle_wms/_exports_lazy_part_01.py:9-41, src/flext_oracle_wms/__init__.py:46-63
The MRO Cascade and FLEXT Integration
The library's integration points are governed by a parent MRO (Method Resolution Order) chain. This cascade is encoded in the inheritance lists of facade classes. Compliance is verified through quality gates like FlextMroViolation checks during testing.
The class diagram illustrates how the lazy-exported API facade integrates with core FLEXT patterns like the result pattern (r) and dispatcher (d).
Sources: README.md:24-28, src/flext_oracle_wms/_exports_lazy_part_01.py:34-40
Utility and Test Lazy Exports
The lazy export system extends beyond the public API into internal utilities and the test suite. This ensures that even development-time tools follow the same performance-optimized loading patterns.
Internal Utility Sub-mapping
The _utilities package uses its own _LAZY_IMPORTS map to handle specialized logic:
- Authentication:
FlextOracleWmsUtilitiesAuth - HTTP Client:
FlextOracleWmsUtilitiesHttpClient - Discovery:
FlextOracleWmsUtilitiesDiscovery
Sources: src/flext_oracle_wms/_utilities/__init__.py:32-40
Test Suite Export Map
The test suite utilizes a comprehensive mapping (TESTS_FLEXT_ORACLE_WMS_LAZY_IMPORTS_PART_01) to manage mock pipelines and unit test classes, allowing the test runner to load only what is necessary for specific test segments.
TESTS_FLEXT_ORACLE_WMS_LAZY_IMPORTS_PART_01 = build_lazy_import_map(
{
".unit.test_client": ("TestsFlextOracleWmsClient",),
".unit.test_config": ("TestsFlextOracleWmsConfig",),
".unit.test_discovery": ("TestsFlextOracleWmsDiscovery",),
".utilities": ("TestsFlextOracleWmsUtilities",),
},
)
Sources: tests/_exports_lazy_part_01.py:9-45
Implementation Mechanics
The core implementation involves a three-step process within the package entry points:
- Define Eager Exports: Metadata required for package identification (e.g.,
__version__). - Define Public Surface: A tuple
_PUBLIC_EXPORTSthat explicitly lists strings of all names to be exposed. - Install Lazy Exports: Calling
install_lazy_exportswhich hooks into the Python import system to trigger real imports only when a member of_PUBLIC_EXPORTSis accessed.
Sources: src/flext_oracle_wms/__init__.py:20-63, src/README.md:143-146
Summary
The Lazy Export & MRO System provides the foundational performance and structural integrity for the flext-oracle-wms library. By strictly managing how and when modules are loaded, it enables rapid entity discovery and ensures full compatibility with the FLEXT ecosystem's declarative standards and MRO inheritance requirements.