Strict Python Patterns

Relevant source files

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

• AGENTS.md
• codex.md
• pyproject.toml
• libs/init.py
• examples/advanced_processing_example.py
• CLAUDE.md

Strict Python Patterns in the FLEXT ecosystem represent a mandatory set of architectural and coding standards designed to ensure type safety, consistency, and enterprise-grade reliability across all flext-* packages. These patterns are governed by a canonical engineering law that mandates the use of modern Python features (3.13+), strict typing, and functional programming paradigms such as the Railway Pattern.

The primary goal of these patterns is to eliminate "ad-hoc" code, bypasses, and untyped data structures (Any), replacing them with validated, typed primitives and centralized facades. This governance is enforced through a suite of tools including Ruff, Pyrefly, Pyright, and Mypy, ensuring that even non-production code like examples and tests meet the same rigor as core library source.

Sources: AGENTS.md:144-155, README.md:1-10, CLAUDE.md:1-10

Core Architectural Constraints

The FLEXT architecture is built on a foundation of strict constraints that dictate how code is structured, named, and validated. These constraints are designed to minimize technical debt and maximize reuse through Method Resolution Order (MRO) and project facades.

Stack and Style Requirements

All development within the workspace must adhere to a specific toolchain and stylistic baseline.

Component	Requirement
Python Version	3.13+ (Strictly enforced)
Type Validation	Pydantic v2
Linting/Formatting	Ruff
Static Analysis	Pyrefly, Pyright, Mypy
Pattern	MRO namespace classes and project facades

Sources: pyproject.toml:21-25, AGENTS.md:180-185

Mandatory Project Facades

FLEXT utilizes standardized single-letter aliases for core concerns to maintain consistency across the monorepo.

• c: Constants (flext_core.constants)
• m: Models (flext_core.models)
• r: Results/Railway Pattern (flext_core.result)
• t: Typings (flext_core.typings)
• u: Utilities (flext_core.utilities)
• p: Protocols (flext_core.protocols)
• s: Services (flext_core.service)

Sources: libs/init.py:15-30, AGENTS.md:190-195

Functional Patterns and Type Safety

FLEXT moves away from traditional exception-based control flow in favor of functional patterns that treat failures as first-class data.

The Railway Pattern (r[T])

The Railway Pattern is the standard for fallible application paths. Instead of raising exceptions, functions return a Result object (r[T]) that explicitly represents either success or failure. This allows for linear pipeline execution where operations "short-circuit" on the first error.

Strict Type Discipline

The project enforces a "zero-tolerance" policy for Any, object, or untyped imports. Every boundary between modules must be strictly typed, often utilizing Pydantic for runtime validation of dynamic payloads.

• Option Bags: Use model_validate(kwargs) for dynamic inputs rather than raw dictionary manipulation.
• Lazy Exports: Packages use install_lazy_exports to manage public API surfaces efficiently while maintaining strict type checking during development.
• Protocol-Based Design: Interfaces are defined using structural typing (Protocols) to decouple implementations from consumers.

Sources: codex.md:8-12, AGENTS.md:167-169, libs/init.py:60-80

Implementation Standards

Pipeline Architecture

Advanced processing in FLEXT is implemented through declarative pipelines. These pipelines often incorporate parallel execution via ThreadPoolExecutor while maintaining the safety of the Railway Pattern.

Key Implementation Rules

1. Truth with Evidence: No claim of "fixed" or "working" is valid without exact command output and exit status.
2. One Owner: Every configurable fact must have a Single Source of Truth (SSOT), typically in config/*.yaml or typed settings models.
3. No Bypass: Manual kwargs normalization or type casting is prohibited if Pydantic can own the payload.
4. Continuous Green: The tree must be importable and pass all lint/type gates at every instant, including in examples/ and tests/.

Sources: AGENTS.md:25-50, codex.md:14-15

Governance and Quality Gates

Strict Python Patterns are not suggestions; they are enforced by a hierarchy of authority and automated gates.

Gate	Tool	Scope
First Gate	ruff	Style, complexity, and basic linting
Logic Gate	pyrefly	Structural analysis and pattern enforcement
Type Gate	pyright / mypy	Strict type checking and protocol compliance
Execution Gate	pytest	Functional validation with coverage requirements

Sources: pyproject.toml:130-180, AGENTS.md:55-70

The quality gates apply to all code tiers, ensuring that a test or example script never assumes values that belong in configuration. If a test breaks because of a legitimate config change, the test is considered defective and must be fixed forward.

Sources: AGENTS.md:13-24

Conclusion

Strict Python Patterns in FLEXT ensure that the enterprise data integration platform remains robust, maintainable, and predictable. By mandating the Railway Pattern for error handling, Pydantic for data validation, and strict typing for all interfaces, the project eliminates common failure modes associated with ad-hoc Python development. This "engineering law" serves as the foundation for the entire ecosystem, ensuring every flext-* package behaves as a first-class citizen within the platform.