Module Export System

Relevant source files

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

• src/flext_target_oracle_oic/_exports.py
• src/flext_target_oracle_oic/_exports_lazy_part_01.py
• src/flext_target_oracle_oic/__init__.py
• src/flext_target_oracle_oic/_utilities/__init__.py
• tests/__init__.py
• src/flext_target_oracle_oic/__version__.py

The Module Export System in flext-target-oracle-oic is a specialized architecture designed to manage the exposure of package components through lazy loading. This system ensures that heavy dependencies and internal modules are only initialized when accessed, significantly improving the startup performance of the Singer target. It centralizes the definition of the public API surface while maintaining a clean separation between eager metadata (like versioning) and lazy-loaded logic (like sinks and utilities).

Sources: src/flext_target_oracle_oic/init.py:1-63, src/flext_target_oracle_oic/_exports.py:1-40

Architecture Overview

The system operates using a multi-layered registration process. Metadata is exported eagerly, while functional components (classes, services, and utilities) are registered via import maps. These maps are processed by the flext_core.lazy utility, specifically the install_lazy_exports function, which hooks into the Python module's attribute access.

Export Layers

The architecture consists of three primary layers:

1. Metadata Layer: Handles package information (version, author, license) defined in __version__.py.
2. Registry Layer: Aggregates lazy import maps from various "parts" to form a complete registry.
3. Facade Layer: The top-level __init__.py that presents the consolidated public interface to consumers.

The diagram above illustrates the flow of definitions from internal parts and metadata files to the public facade.
Sources: src/flext_target_oracle_oic/init.py:7-54, src/flext_target_oracle_oic/_exports.py:9-38

Lazy Import Mechanism

The core of the system is the build_lazy_import_map and merge_lazy_imports functions. These utilities define which local submodules or external packages provide specific symbols.

Import Map Structure

The FLEXT_TARGET_ORACLE_OIC_LAZY_IMPORTS_PART_01 map defines the relationship between internal paths and their exported symbols. For example, symbols from .api, .cli, and .models are mapped so they are not imported until the user explicitly references FlextTargetOracleOicService, FlextTargetOracleOicCli, or the shorthand m.

Mapping Path	Exported Symbols
.api	FlextTargetOracleOicService, target_oracle_oic
.cli	FlextTargetOracleOicCli, main
.constants	FlextTargetOracleOicConstants, c
.models	FlextTargetOracleOicModels, m
.utilities	FlextTargetOracleOicUtilities, u
flext_core	d, e, h, r, s, x

Sources: src/flext_target_oracle_oic/_exports_lazy_part_01.py:9-52

Consolidation and Governance

The _exports.py file acts as a central hub. It merges part-specific maps and applies governance rules, such as excluding internal testing hooks (pytest_addoption, output_reporting) and internal utilities (logger, lazy_getattr) from being published in the public lazy registry.

FLEXT_TARGET_ORACLE_OIC_LAZY_IMPORTS = merge_lazy_imports(
    (),
    _LOCAL_LAZY_IMPORTS,
    exclude_names=(
        "cleanup_submodule_namespace",
        "install_lazy_exports",
        "logger",
        # ... additional internal symbols excluded
    ),
    module_name="flext_target_oracle_oic",
)

Sources: src/flext_target_oracle_oic/_exports.py:14-38

Versioning and Metadata

While most components are lazy, package metadata is defined in __version__.py and exported eagerly. This allows tools like pip and documentation generators to access version info without triggering the full module loading logic.

The FlextTargetOracleOicVersion class inherits from FlextVersion and leverages importlib.metadata to retrieve the version dynamically from the installed package metadata.

Metadata Attribute	Source Origin
__version__	FlextTargetOracleOicVersion.__version__
__title__	FlextTargetOracleOicVersion.__title__
__author__	FlextTargetOracleOicVersion.__author__
__license__	FlextTargetOracleOicVersion.__license__

Sources: src/flext_target_oracle_oic/version.py:16-35

Component Flow

When a consumer interacts with the package, the following sequence occurs:

The sequence shows how the first access triggers the physical import of the underlying submodule.
Sources: src/flext_target_oracle_oic/init.py:57-62, src/flext_target_oracle_oic/_exports_lazy_part_01.py:13-16

Testing Infrastructure Exports

The export system is mirrored in the tests directory. The tests/__init__.py file uses the same lazy loading pattern to manage test-specific dependencies, such as flext_tests helpers and unit test classes. This prevents the test suite from loading unnecessary modules during initial discovery by pytest.

Sources: tests/init.py:12-140

Conclusion

The Module Export System provides a robust and performant interface for the Oracle OIC target. By strictly controlling the public namespace and deferring imports, the project maintains a high degree of technical governance while ensuring a lightweight footprint for CLI and library usage.