Lazy Export Bootstrapping

Lazy Export Bootstrapping is a performance-oriented architectural pattern used within the flext-tap-oracle-wms project to manage module loading. By deferring the actual import of heavy components until they are specifically accessed, the system reduces initial memory overhead and improves the startup time of the Singer tap. This mechanism relies on flext_core.lazy utilities to map public interfaces to their underlying implementation files without triggering immediate execution of those files.

Sources: src/flext_tap_oracle_wms/init.py:1-60, src/flext_tap_oracle_wms/_exports.py:1-40

Architecture and Registry

The bootstrapping process is structured across three layers: the Lazy Import Map, the Export Registry, and the Package Entry Point. The system uses a partitioned approach, where maps are built in "parts" to allow for granular management of the module namespace.

Bootstrapping Flow

The following diagram illustrates how the package initializes and exposes its members using lazy loading.

The diagram shows the hierarchy from the top-level package initialization down to the specific lazy import part definitions.
Sources: src/flext_tap_oracle_wms/init.py:53-58, src/flext_tap_oracle_wms/_exports.py:12-28

Key Components

Sources: src/flext_tap_oracle_wms/_exports_lazy_part_01.py:8-44, src/flext_tap_oracle_wms/_exports.py:8-15

Lazy Import Mapping

The core logic of the bootstrapping is defined in the import map. This map associates relative module paths with specific identifiers. For instance, the FlextTapOracleWms class is mapped to the .tap module.

Namespace Resolution

When a consumer accesses a member from the package, the lazy loader resolves it based on the following mapping structure:

The graph represents the logical mapping of high-level exports to their internal module locations.
Sources: src/flext_tap_oracle_wms/_exports_lazy_part_01.py:10-43

Implementation Detail: Import Map

The FLEXT_TAP_ORACLE_WMS_LAZY_IMPORTS_PART_01 defines the relationship between the local module aliases and the public identifiers.

FLEXT_TAP_ORACLE_WMS_LAZY_IMPORTS_PART_01 = build_lazy_import_map(
    {
        ".api": ("FlextTapOracleWmsService", "tap_oracle_wms"),
        ".cli": ("main",),
        ".constants": ("FlextTapOracleWmsConstants", "c"),
        ".tap": ("FlextTapOracleWms",),
        "flext_core": ("d", "e", "h", "r", "s", "x"),
    },
)

Sources: src/flext_tap_oracle_wms/_exports_lazy_part_01.py:10-44

Bootstrapping in Tests

The lazy bootstrapping pattern is replicated within the tests directory to ensure that the testing suite remains performant and avoids unnecessary side effects during test collection.

Test Submodule Initialization

Each test category (unit, integration, performance) implements its own lazy export map. This ensures that a pytest run targeting only unit tests does not load the integration or performance test dependencies.

This sequence shows how the test package prepares symbols without loading the full test suite into memory.
Sources: tests/init.py:101-155, tests/unit/init.py:8-33

Test Registry Exclusions

During the merge of lazy imports for tests, specific names are excluded to prevent namespace collisions or the accidental exposure of test runners and reporting utilities. Excluded names include:

• pytest_configure
• pytest_runtest_setup
• output_reporting
• cleanup_submodule_namespace

Sources: tests/init.py:158-177, src/flext_tap_oracle_wms/_exports.py:16-36

Summary of Public Exports

The following identifiers are bootstrapped and available as the public surface of the flext_tap_oracle_wms package:

Sources: src/flext_tap_oracle_wms/init.py:29-51, src/flext_tap_oracle_wms/_exports_lazy_part_01.py:10-43

Lazy Export Bootstrapping serves as the foundation for the project's "Zero-Debt" and high-performance goals by ensuring that the WMS tap infrastructure is only initialized when the Singer protocol execution actually begins. This is critical in enterprise environments where resource constraints and startup latency are significant factors.