Module Exports and Facades

Relevant source files

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

• src/flext_core/__init__.py
• src/flext_core/history.json
• examples/__init__.py
• tests/__init__.py
• src/flext_core/_utilities/_project_metadata_parts/project_metadata_part_03.py
• src/flext_core/_constants/_enforcement_parts/flextconstantsenforcement_part_09.py

Module Exports and Facades constitute the public interface layer of the FLEXT-Core framework. This system utilizes a "Thin MRO Facade" pattern, where large, complex functionalities are decomposed into internal parts and then recomposed into high-level, single-letter aliases (e.g., c, m, u, r) for consumer use. This architecture ensures a clean separation between internal implementation details and the stable public API, while supporting modern Python features like lazy loading to optimize startup performance.

The system is governed by strict "Import Laws" that enforce how facades are structured, how they inherit from internal parts, and how aliases are exposed at the package root. This approach minimizes circular dependencies and ensures that the Method Resolution Order (MRO) correctly linearizes the various specialized mixins and base classes that form each facade.

Sources: src/flext_core/history.json, src/flext_core/_constants/_enforcement_parts/flextconstantsenforcement_part_09.py:17-50

Architecture of Facades and Aliases

The framework organizes its logic into functional tiers. Facades act as the entry point for these tiers, aggregating multiple specialized classes into a single unified object. This is primarily achieved through multiple inheritance, where a facade class (like FlextConstants or FlextTypes) inherits from several "parts" modules.

The Thin MRO Facade Pattern

Each major functional area (Constants, Models, Utilities, etc.) is exposed via a facade class. These classes serve as namespaces that provide access to all underlying attributes and methods via the Python MRO.

This diagram illustrates how a unified facade class aggregates various functional parts and is then exposed to consumers through a simplified single-letter alias.
Sources: src/flext_core/history.json

Core Public Aliases

FLEXT-Core defines a standardized set of single-letter aliases that are exported from the package root. These aliases provide immediate access to the framework's primary services.

Alias	Facade Class	Functional Scope
c	FlextConstants	Global constants, enforcement rules, and configuration defaults.
m	FlextModels	Domain models, Pydantic entities, and metadata structures.
u	FlextUtilities	Static helpers, text processing, and project metadata readers.
t	FlextTypes	Type aliases, generics, and Pydantic-aware typing foundations.
p	FlextProtocols	Structural typing contracts and interface definitions.
r	FlextResult	Railway-oriented programming (ROP) primitives and result handling.

Sources: src/flext_core/init.py:118-132, src/flext_core/history.json

Export Mechanisms and Lazy Loading

To maintain a fast startup time despite a large number of internal modules, FLEXT-Core employs a lazy loading mechanism for its exports. Package __init__.py files do not import concrete classes directly at the top level; instead, they define an import map that is processed at runtime when an attribute is first accessed.

Lazy Export Workflow

1. Map Definition: A _LAZY_IMPORTS dictionary maps alias names to their internal module paths.
2. Installation: The install_lazy_exports function registers these names in the module's __all__ and sets up __getattr__ to perform the actual import on demand.
3. Type Checking: For IDE support and static analysis, if TYPE_CHECKING: blocks provide explicit imports that are ignored at runtime.

This flow shows how the lazy loading mechanism intercept attribute access to import modules only when required.
Sources: src/flext_core/init.py:136-160, examples/init.py:134-150

Import Enforcement and Rules

The framework enforces strict rules on how facades and exports are implemented to prevent architectural drift and circular dependencies. These are codified as "Import Laws" (e.g., AGENTS.md §4).

Key Enforcement Rules

• Alias Rebinding: Every canonical facade module must rebind its alias at the very end of the file (e.g., t = FlextTypes).
• MRO Ordering: Multi-parent facades must list the canonical alias or alias-base first to ensure correct C3 MRO linearization.
• No Concrete Imports: Facade files must import only aliases (c/m/p/t/u) from parents, never bare concrete classes.
• One Class Per Module: Modules are restricted to exactly one top-level class to encourage decomposition.

Sources: src/flext_core/_constants/_enforcement_parts/flextconstantsenforcement_part_09.py:17-50

Metadata Discovery

The FlextUtilitiesProjectMetadata class provides helpers to discover these aliases and their sources within a distribution. It can scan installed packages to find one-letter aliases exported via __all__ and identify their parent sources.

Method	Description
_discover_eager_alias_parent_sources	Scans a package for one-letter, lowercase aliases and identifies their originating module.
read_project_constants	Aggregates package metadata, lazy alias tables, and facade prefixes into a ProjectConstants object.
_scan_directories	Identifies standard FLEXT directories like src, tests, and examples.

Sources: src/flext_core/_utilities/_project_metadata_parts/project_metadata_part_03.py:34-115

Conclusion

The Module Exports and Facades system in FLEXT-Core provides a highly structured and optimized entry point for the framework. By utilizing lazy-loaded Thin MRO Facades, the project achieves a balance between comprehensive functionality and performance. The enforcement of single-letter aliases and strict import rules ensures that the public API remains consistent and discoverable across all modules in the ecosystem.