Introduction & Core Concepts
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT-Core serves as the Enterprise Foundation Framework for modern Python 3.13 applications, emphasizing Clean Architecture, Domain-Driven Design (DDD), and Railway-Oriented Programming (ROP) patterns. It provides a standardized baseline for platform-class projects, ensuring strict typing, explicit dependency management, and high-performance execution through features like lazy-loaded exports and Method Resolution Order (MRO) facades.
The framework is designed to eliminate boilerplate in enterprise applications by providing robust abstractions for result handling, dependency injection, context propagation, and project metadata management. It acts as the "Layer 0" foundation upon which other ecosystem packages and business applications are built.
Sources: README.md:1-12, pyproject.toml:44-50, examples/README.md:18-24
Core Architectural Patterns
Railway-Oriented Programming (ROP)
The framework adopts ROP via the FlextResult (aliased as r) to handle success and failure paths explicitly without relying on exception-based flow control for expected domain errors. Operations return a Result object that can be chained using functional combinators like map, flat_map, and lash.
The diagram shows the "Happy Path" vs "Error Path" logic where failures short-circuit standard execution unless explicitly recovered.
Sources: examples/README.md:32-34, tests/integration/test_system.py:34-110
Dependency Injection (DI)
FlextContainer provides a centralized registry for services and configurations. It supports fluent binding (bind) and resolution (resolve) of dependencies, enabling clean separation of concerns and easier testing through mock substitution.
Sources: examples/README.md:37-38, tests/integration/test_system.py:195-209
MRO-Based Facades
FLEXT-Core utilizes "Thin MRO Facades" for its core modules like FlextConstants (c), FlextModels (m), and FlextTypes (t). These classes aggregate functionality from multiple sub-modules via inheritance, allowing a single import point while maintaining internal modularity.
This structure ensures that all constants or types are accessible through a single namespace (e.g., c.DEFAULT_TIMEOUT_SECONDS) without duplicating attributes across the inheritance chain.
Sources: src/flext_core/history.json:20-56, src/flext_core/history.json:115-132
Project Metadata & Configuration (SSOT)
FLEXT-Core implements a Single Source of Truth (SSOT) for project metadata, primarily derived from pyproject.toml. This system handles project naming conventions, versioning, and environment-specific settings.
Metadata Models
The framework uses Pydantic v2 models to enforce immutability and strict validation on metadata.
| Component | Description | Source |
|---|---|---|
ProjectMetadata | Immutable model containing name, version, license, and root path. | tests/unit/test_project_metadata_facade_access.py:110-120 |
pascalize | Utility to convert kebab/snake-case project names to PascalCase. | tests/unit/test_project_metadata_facade_access.py:38-55 |
derive_class_stem | Logic to determine the standard prefix for project classes (e.g., flext-core -> Flext). | tests/unit/test_project_metadata_facade_access.py:57-73 |
FlextSettings | Handles configuration loading, validation, and environment prefixing. | examples/README.md:40-41 |
Sources: src/flext_core/_models/_project_metadata_parts/flextmodelsprojectmetadata_part_02.py:27-50, tests/unit/test_project_metadata_facade_access.py:38-120
Public API and Lazy Loading
To maintain a clean public surface while ensuring performance, FLEXT-Core employs a lazy-loading mechanism. The root __init__.py uses install_lazy_exports to manage the public namespace without importing every module into memory immediately.
Primary Facade Aliases
For brevity and consistency across the ecosystem, the following short-hand aliases are standardized:
| Alias | Full Name | Purpose |
|---|---|---|
c | FlextConstants | Global constants and error codes |
m | FlextModels | Pydantic models and domain entities |
t | FlextTypes | Type aliases and generics |
u | FlextUtilities | Helper functions and logic |
r | FlextResult | Railway-oriented result handling |
e | FlextExceptions | Structured exception hierarchy |
p | FlextProtocols | Structural typing and interfaces |
Sources: src/flext_core/init.py:165-188, src/flext_core/history.json:134-143
Summary
Introduction & Core Concepts of FLEXT-Core focus on creating a rigid yet flexible foundation for enterprise Python. By combining strict typing (t), centralized constants (c), immutable models (m), and functional error handling (r), the framework establishes a predictable runtime environment. This architecture allows developers to focus on domain logic while the framework handles cross-cutting concerns like dependency injection, observability through FlextContext, and metadata-driven configuration.
Sources: README.md:1-12, examples/README.md:73-77