Module Exports & Lazy Loading

Relevant source files

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

• src/flext_oracle_oic/_exports.py
• src/flext_oracle_oic/_exports_lazy_part_01.py
• src/flext_oracle_oic/__init__.py
• src/flext_oracle_oic/services/__init__.py
• src/flext_oracle_oic/_utilities/__init__.py
• tests/__init__.py

Introduction

The flext-oracle-oic project implements a sophisticated lazy-loading architecture to optimize initialization time and manage module dependencies. This system ensures that heavy components, such as service mixins, utility classes, and external library integrations, are only imported when actually accessed by the application. This is particularly critical for a library providing advanced Oracle Integration Cloud (OIC) extensions, where multiple specialized services (CRUD, monitoring, orchestration) might coexist but not all be required for a single execution path.

Sources: src/flext_oracle_oic/init.py, src/flext_oracle_oic/_exports.py

Lazy Loading Architecture

The architecture relies on a registry-based system where export maps are built and then installed into the module's global namespace. This process is orchestrated through the flext_core.lazy utility suite, which provides functions for building, merging, and installing these maps.

Export Registry Flow

The loading process follows a hierarchical structure where individual module parts define their exports, which are then aggregated into a central registry.

The flow starts in _exports_lazy_part_01.py using build_lazy_import_map, is merged in _exports.py, and finally installed in the package root.
Sources: src/flext_oracle_oic/_exports_lazy_part_01.py:1-45, src/flext_oracle_oic/_exports.py:1-32, src/flext_oracle_oic/init.py:60-65

Key Components and Export Maps

Export Map Structure

The export maps define a mapping between local aliases (prefixed with . for relative imports) and the actual classes or modules they represent.

Alias/Module	Exported Members	Source File
.api	FlextOracleOicApi, oracle_oic	_exports_lazy_part_01.py
.constants	FlextOracleOicConstants, c	_exports_lazy_part_01.py
.models	FlextOracleOicModels, m	_exports_lazy_part_01.py
.services.auth	FlextOracleOicAuthMixin	_exports_lazy_part_01.py
.services.monitoring	FlextOracleOicMonitoringMixin	_exports_lazy_part_01.py
flext_core	d, e, h, r, x	_exports_lazy_part_01.py

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

Public Surface Configuration

The package differentiates between internal lazy imports and the public API surface. The _PUBLIC_EXPORTS tuple in the root __init__.py defines the canonical interface exposed to consumers.

_PUBLIC_EXPORTS: tuple[str, ...] = (
    "FlextOracleOicApi",
    "FlextOracleOicAuthMixin",
    "FlextOracleOicCli",
    "FlextOracleOicConstants",
    "FlextOracleOicIntegrationCrudMixin",
    # ...
    "c",
    "m",
    "p",
    "s",
    "t",
    "u"
)

Sources: src/flext_oracle_oic/init.py:31-72

Submodule Implementations

Service Mixins

The services directory utilizes its own lazy loading mechanism to handle various OIC operational mixins. This allows the FlextOracleOicService facade to stay lightweight until specific functionality is invoked.

Utilities Package

Similar to services, the utilities package uses build_lazy_import_map to manage internal tools like authentication validation and health monitoring.

Utility Path	Component
.authentication_validation	FlextOracleOicUtilitiesAuthenticationValidation
.monitoring	FlextOracleOicUtilitiesMonitoring
.oracle_oic	FlextOracleOicUtilitiesOracleOic

Sources: src/flext_oracle_oic/_utilities/init.py:10-38

Test Suite Integration

The testing framework mimics the production lazy loading pattern. This ensures that tests execute in an environment that accurately reflects the module's runtime behavior. The tests/__init__.py file merges local unit test modules with flext_tests core utilities.

Conclusion

The lazy loading system in flext-oracle-oic provides a structured, auto-generated approach to module management. By separating eager metadata exports (like versioning) from heavy functional components, the package maintains a minimal memory footprint and fast startup times while exposing a comprehensive, typed API surface.