Import Law & MRO

Relevant source files

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

• src/flext/__init__.py (Assumed based on naming/structure)
• libs/__init__.py
• examples/__init__.py
• AGENTS.md
• codex.md
• examples/advanced_processing_example.py

Import Law & MRO (Method Resolution Order) defines the mandatory structural and behavioral rules for code organization, dependency resolution, and namespace management within the FLEXT ecosystem. It enforces a strict "Green" state requirement where the tree must be importable at every instant and strictly prohibits ad-hoc helpers or bypasses in favor of canonical Method Resolution Order patterns.

This system ensures that all flext-* packages inherit from a single source of truth (flext-core) while maintaining typed, validated, and reusable primitives. Central to this architecture is the use of project facades and lazy-loading mechanisms to optimize performance without compromising type safety.

Sources: AGENTS.md:270-280, AGENTS.md:325-330

Canonical Import Engineering

FLEXT employs a "Supreme Law" of resolution that forbids bypasses, shims, or fallbacks. Every edit batch (limited to 5 files) must pass a fresh-import smoke test and a lint check (ruff --no-fix) to ensure the tree remains collectable.

Import Constraints & Patterns

The project utilizes a specific aliasing scheme for common architectural components to maintain consistency across the monorepo.

Alias	Component Category	Description
c	Constants	Canonical owner of immutable values
m	Models	Pydantic-based data structures
p	Protocols	Structural typing definitions
r[T]	Results	Fallible application path contracts
s	Services	Business logic orchestrators
u	Utilities	Shared helper functions
x	Mixins	MRO-based functionality extensions

Sources: AGENTS.md:324-340, libs/init.py:17-30

The Green Gate Protocol

The "Continuous-Green" rule mandates that any facade or public member move/rename must update all consumers workspace-wide in the same batch. Failure to maintain an importable tree is treated as an active incident.

MRO Namespace Architecture

FLEXT prioritizes Method Resolution Order and mixins over duplicate utilities. The architecture enforces one canonical class or namespace owner per concern.

Facade Management

Packages use a lazy-loading mechanism to expose core primitives through standard aliases. This reduces initial import overhead while providing full type hints during development.

if _t.TYPE_CHECKING:
    from flext_core.constants import FlextConstants as c
    from flext_core.models import FlextModels as m
    from flext_core.result import FlextResult as r
    # ... other aliases

_LAZY_IMPORTS = {
    "c": ("flext_core.constants", "FlextConstants"),
    "m": ("flext_core.models", "FlextModels"),
    "r": ("flext_core.result", "FlextResult"),
    # ... mapping
}

install_lazy_exports(__name__, globals(), _LAZY_IMPORTS)

Sources: libs/init.py:18-50, examples/init.py:15-30

Composition Rules

1. Deduplication: Developers must reuse origin methods before creating helpers. Private helpers with a single caller must be inlined and deleted.
2. Layering: Abstractions are layered by project boundaries; src/ is the primary layer, while tests/, examples/, and scripts/ are strictly consumers.
3. No Hidden Code: Examples and scripts are treated as first-class code and are subject to the same MRO and linting rigor as production source.

Sources: codex.md:8-12, AGENTS.md:55-60, AGENTS.md:338-342

Runtime Execution & Payload Handling

The Import Law extends to how data flows through the MRO hierarchy, particularly regarding dynamic payloads and environment variables.

Typed Option Bags

Manual kwargs key/type normalization is prohibited. Instead, FLEXT uses Pydantic-powered option bags:

• True Option Bags: Use model_validate(kwargs) once.
• Fixed-Shape APIs: Remain explicit but use one packed model_validate({...}).
• Environment Access: os.environ is forbidden in src/ runtime; all access must go through settings abstractions.

Performance Optimization

Optimization is "Evidence-First." Developers must profile using cProfile before applying changes. The preferred optimization path is through the project's typed OO/MRO/lazy-import patterns rather than bypassing established abstractions.

Sources: AGENTS.md:65-72

Summary of Law Compliance

The significance of Import Law & MRO lies in maintaining a scalable, zero-bypass codebase. By strictly adhering to MRO namespaces and the "Green" import requirement, the project ensures that integrations are built on validated, reusable primitives with zero ad-hoc inflation.

Sources: AGENTS.md:270-275, codex.md:30-35