Package Exports and Lazy Loading

Relevant source files

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

• src/flext_tap_oracle/__init__.py
• src/flext_tap_oracle/_exports.py
• src/flext_tap_oracle/_exports_lazy_part_01.py
• src/flext_tap_oracle/_utilities/__init__.py
• tests/__init__.py
• tests/unit/__init__.py

The flext-tap-oracle package employs a sophisticated lazy loading architecture designed to optimize startup time and memory footprint. By deferring the import of heavy modules until they are actually accessed, the package ensures that CLI invocations and library integrations remain responsive. This system is built upon flext_core.lazy utilities and utilizes a structured registry of export maps.

Sources: src/flext_tap_oracle/__init__.py:6-15, src/flext_tap_oracle/_exports_lazy_part_01.py:8-12

Architecture and Export Registry

The lazy loading system is organized into a hierarchy of export definitions. At the base, specific "parts" define the mapping between local modules and their exported symbols. These parts are then consolidated into a central registry that the package's __init__.py uses to install the lazy exports into the global namespace.

Export Map Structure

The export map is constructed using build_lazy_import_map, which associates relative or absolute module paths with tuples of strings representing the classes, functions, or variables to be exported.

The diagram shows how the top-level package resolves lazy imports through nested export definitions.
Sources: src/flext_tap_oracle/_exports_lazy_part_01.py:8-48, src/flext_tap_oracle/_exports.py:8-12

Components of the Export System

Component	Responsibility	Source File
FLEXT_TAP_ORACLE_LAZY_IMPORTS_PART_01	Defines the mapping for primary domain modules (API, Models, Settings).	_exports_lazy_part_01.py
FLEXT_TAP_ORACLE_LAZY_IMPORTS	The merged registry combining all lazy parts and applying exclusions.	_exports.py
install_lazy_exports	Utility that hooks into __getattr__ and __dir__ to enable lazy behavior.	flext_core.lazy
_PUBLIC_EXPORTS	Explicit list of symbols exposed at the package root.	__init__.py

Sources: src/flext_tap_oracle/__init__.py:28-65, src/flext_tap_oracle/_exports.py:14-38

Core Module Mappings

The following table summarizes the primary module mappings defined in the lazy export parts. These mappings allow developers to access sub-module functionality directly from the root flext_tap_oracle package without manual sub-importing.

Module Path	Exported Symbols	Alias / Namespace
.api	FlextTapOracleService, tap_oracle	Service Interface
.models	FlextTapOracleModels, m	Data Models
.settings	FlextTapOracleSettings	Configuration
.tap	FlextTapOracleCli, FlextTapOracleDiscoverCommand, FlextTapOracleSyncCommand	CLI Components
.utilities	FlextTapOracleUtilities, u	Helper Functions
flext_core	d, e, h, r, s, x	Core Framework Utilities

Sources: src/flext_tap_oracle/_exports_lazy_part_01.py:10-48

Test Suite Lazy Loading

The testing infrastructure mirrors the production lazy loading pattern to ensure consistency and performance during test execution. The tests and tests.unit packages use a similar registry-based approach to expose test utilities and models.

The sequence diagram illustrates the deferred loading of test utilities during a test session.
Sources: tests/__init__.py:63-125, tests/unit/__init__.py:8-33

Implementation Detail: _exports.py

The package uses a localized _exports.py to consolidate the lazy parts. This file performs the final merge and excludes specific internal utility names from the public namespace to prevent pollution.

_LOCAL_LAZY_IMPORTS = {
    **FLEXT_TAP_ORACLE_LAZY_IMPORTS_PART_01,
}

FLEXT_TAP_ORACLE_LAZY_IMPORTS = merge_lazy_imports(
    (),
    _LOCAL_LAZY_IMPORTS,
    exclude_names=(
        "cleanup_submodule_namespace",
        "install_lazy_exports",
        "lazy_getattr",
        "logger",
        # ... additional exclusions
    ),
    module_name="flext_tap_oracle",
)

Sources: src/flext_tap_oracle/_exports.py:8-38

Initialization and Metadata

The package __init__.py performs two distinct types of exports:

1. Eager Exports: Version and authorship metadata (e.g., __version__, __author__) are loaded immediately from __version__.py.
2. Lazy Exports: Domain-specific classes and services are registered for lazy loading.

This distinction ensures that package metadata is always available for inspection (e.g., by pip or importlib.metadata) without triggering the full overhead of database drivers or Singer SDK components.

Sources: src/flext_tap_oracle/__init__.py:17-26, src/flext_tap_oracle/__init__.py:68-73

Summary

The lazy loading system in flext-tap-oracle provides a robust mechanism for managing complex dependencies in an Oracle-integrated environment. By utilizing structured import maps and a central registry, the project achieves a high degree of modularity while maintaining a clean and performant public API surface for both developers and the runtime environment.