Lazy Exports Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_plugin/_exports_lazy_part_01.py
• src/flext_plugin/_exports.py
• src/flext_plugin/init.py
• tests/init.py
• src/flext_plugin/_utilities/init.py
• tests/unit/init.py

Lazy Exports Management is a core architectural pattern in the flext-plugin project used to optimize module loading times and manage complex dependency trees. By deferring the actual import of heavy modules until they are accessed, the system reduces the initial memory footprint and avoids circular dependency issues common in large plugin architectures.

The system relies on a central registry of import maps that define how symbols should be resolved across the package. These maps are processed by the flext_core.lazy utility, which intercepts attribute access on modules to perform "just-in-time" loading of the required components.

Sources: src/flext_plugin/init.py:1-48, src/flext_plugin/_exports.py:1-41

Architecture and Components

The lazy loading architecture is divided into three distinct layers: the declaration of import parts, the consolidation of the registry, and the installation of the lazy facade.

Component Breakdown

Component	Responsibility	Primary File
Lazy Import Map	Defines the mapping between local aliases/symbols and their actual source modules.	src/flext_plugin/_exports_lazy_part_01.py
Registry Merger	Consolidates multiple lazy parts into a single unified map while handling exclusions.	src/flext_plugin/_exports.py
Lazy Installer	Patches the module's __getattr__ and __dir__ to enable lazy resolution.	src/flext_plugin/init.py

Sources: src/flext_plugin/_exports_lazy_part_01.py:1-41, src/flext_plugin/_exports.py:1-41, src/flext_plugin/init.py:49-54

Execution Flow

The following diagram illustrates how the system transitions from a static map definition to an active lazy-loaded module.

The diagram shows the hierarchical consolidation of import maps from individual parts into a final installed state.
Sources: src/flext_plugin/_exports_lazy_part_01.py:8-39, src/flext_plugin/_exports.py:10-39, src/flext_plugin/init.py:49-54

Implementation Details

Import Map Declaration

The project uses build_lazy_import_map to define which submodules or external packages provide specific symbols. This is often split into "parts" to maintain readability and modularity.

FLEXT_PLUGIN_LAZY_IMPORTS_PART_01 = build_lazy_import_map(
    {
        ".api": ("FlextPluginApi", "plugin"),
        ".models": ("FlextPluginModels", "m"),
        "flext_core": ("d", "e", "h", "r", "s", "x"),
    },
)

Sources: src/flext_plugin/_exports_lazy_part_01.py:8-39

Consolidated Registry

The _exports.py file serves as the main registry. It uses merge_lazy_imports to combine various parts. A critical feature of this layer is the exclude_names parameter, which prevents internal utilities or testing hooks from being exposed as lazy exports.

Common exclusions include:

• pytest_* hooks (e.g., pytest_configure, pytest_sessionstart)
• Logging and reporting utilities (logger, output_reporting)
• Internal lazy machinery (lazy_getattr, install_lazy_exports)

Sources: src/flext_plugin/_exports.py:13-39

Module Installation

In the package's __init__.py, the install_lazy_exports function is called. It takes the current module's globals(), the consolidated _LAZY_IMPORTS, and an explicit list of _PUBLIC_EXPORTS. This ensures that from flext_plugin import ... works seamlessly even though the modules aren't loaded until the line is executed.

Sources: src/flext_plugin/init.py:49-54

Lazy Loading in Tests

The testing suite also adopts the lazy export pattern to ensure that the test environment remains lightweight and avoids side effects during test discovery.

This diagram demonstrates how the test package merges its own unit test modules into the lazy import registry.
Sources: tests/init.py:81-125

In tests/__init__.py, the system merges local unit tests using (".unit",) as a base path, allowing symbols like TestsFlextPluginConfig to be resolved from tests.unit.test_config automatically.

Sources: tests/init.py:82-124

Summary of Exported Symbols

The following table lists the primary categories of symbols managed by the lazy export system in the flext-plugin package.

Symbol Category	Source Path	Examples
Core API	.api	FlextPluginApi, plugin
Data Models	.models	FlextPluginModels, m
Utilities	.utilities	FlextPluginUtilities, u
Constants	.constants	FlextPluginConstants, c
Core Aliases	flext_core	r (Result), s (Service), x (Execution)

Sources: src/flext_plugin/_exports_lazy_part_01.py:11-38, src/flext_plugin/init.py:23-46

Conclusion

Lazy Exports Management is the foundational mechanism for symbol resolution in flext-plugin. By using structured import maps and the flext_core.lazy library, the project achieves a balance between a rich developer-facing API (with many short-hand aliases like m, c, and r) and a performance-oriented loading strategy. This architecture is consistently applied across the main library, utilities, and testing infrastructure.