Getting Started with Examples
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT-Core provides a comprehensive suite of self-contained examples designed to demonstrate Clean Architecture patterns and best practices within the framework. These examples serve as executable documentation, covering foundational concepts such as Railway-Oriented Programming (ROP), dependency injection, and advanced application layer patterns like CQRS dispatching and service execution.
The examples are structured into categories ranging from core foundation patterns to complex integration scenarios. Each example is designed to produce structured output, including success indicators, error handling demonstrations, and context propagation metrics, ensuring that developers can verify the behavior of FLEXT-Core primitives in a production-ready environment.
Sources: examples/README.md:15-22, tests/integration/test_examples_execution.py:7-12
Setup and Execution
To use the examples, the environment must be configured with Python 3.13+. The framework supports installation in development mode to allow for immediate testing of local changes.
# Install FLEXT-Core in development mode
pip install -e .
# Run a specific example
python examples/01_basic_result.py
Execution Contract
Each example script functions as a self-verifying harness. When executed, it compares audited values against committed "golden files" (.expected fixtures). A successful run is indicated by a PASS marker and a report of the number of checks performed.
Sources: examples/README.md:24-33, tests/integration/test_examples_execution.py:48-65
Foundation & Core Patterns
The foundational examples focus on the r[T] outcome contract and the Railway-Oriented Programming (ROP) paradigm.
Railway-Oriented Programming (r)
The r (Result) type is central to FLEXT-Core's error handling. Examples demonstrate how to chain operations using map, flat_map, and lash while maintaining a clean success/failure path.
| Method | Purpose |
|---|---|
map | Transforms a success value; skipped on failure. |
flat_map | Chains a fallible operation; short-circuits on failure. |
lash | Recovers from a failure by replacing it with a new Result. |
traverse | Applies a fallible function to a collection. |
with_resource | Manages resource lifecycle with automatic cleanup. |
Sources: examples/README.md:39-42, examples/ex_01_flext_result_helpers.py:22-140
This diagram illustrates the flow of a Railway-Oriented Programming pipeline where failures short-circuit standard execution.
Application Layer Patterns
Advanced examples demonstrate the orchestration of components through Dispatchers and Services.
Command/Query Dispatching
The FlextDispatcher facilitates the routing of routable messages to specific handlers. It supports various handler types, including protocol-based handlers, callables, and event subscribers.
- Registration: Handlers are registered for specific message types (e.g.,
m.Examples.CreateUser). - Execution: The
dispatch()method routes a command or query to the appropriate handler. - Events: The
publish()method allows multiple subscribers to react to a single message.
Sources: examples/ex_04_flext_dispatcher.py:91-177
Service Execution
The s[T] base class provides a structured way to implement business logic with built-in access to the container, settings, and context.
This sequence shows the standard execution flow of a FLEXT Service, emphasizing internal validation before processing.
Sources: examples/ex_11_flext_service.py:15-39
Shared Test Harness
All examples inherit from a shared base to ensure deterministic behavior during testing and golden-file generation.
Deterministic Helpers
The ExamplesFlextSharedBase provides pseudo-random generators seeded with a constant value to ensure that "random" data remains consistent across test runs for golden-file comparisons.
Key utilities include:
rand_int(lo, hi): Deterministic integer generation.rand_str(length): Deterministic string generation.ser(v): Human-readable serialization for output auditing.
Sources: examples/_shared_parts/shared_part_01.py:16-95
Example Mapping
| Category | File | Key Pattern |
|---|---|---|
| Foundation | 01_basic_result.py | Railway-Oriented Programming basics |
| Dependency Injection | 02_dependency_injection.py | FlextContainer usage and service registration |
| Domain Modeling | 03_models_basics.py | Entities, Values, and Aggregate Roots |
| CQRS | 07_registry_dispatcher.py | Command/Query routing via FlextDispatcher |
| Automation | 15_automation_showcase.py | Context enrichment and tracing |
Sources: examples/README.md:46-75
Conclusion
The examples in FLEXT-Core are not merely snippets but functional components of the test suite. By leveraging the r result pattern, FlextDispatcher, and FlextService, developers can build resilient, observable, and strictly typed enterprise applications. The shared harness ensures that these patterns are easily testable and verifiable against expected behaviors.
Sources: examples/README.md:88-95, tests/integration/test_examples_execution.py:7-12