General Framework Utilities
Relevant source files
The following files were used as context for generating this wiki page:
General Framework Utilities in FLEXT-Core provide a centralized suite of helper modules designed to support domain-driven design (DDD), railway-oriented programming (ROP), and clean architecture patterns. These utilities handle cross-cutting concerns such as data mapping, project metadata discovery, string manipulation, and collection management.
The utility layer is exposed via a facade pattern, often aliased as u in the codebase, allowing for a single entry point to diverse functional areas including FlextUtilitiesMapper, FlextUtilitiesProjectMetadata, and FlextUtilitiesText. These tools are foundational to the framework's ability to maintain a "zero-debt" baseline and enforce strict typing rules.
Sources: src/flext_core/_root_typing.py:126, src/flext_core/_utilities/init.py:1-10, README.md:16-19
Data Mapping and Transformation
The FlextUtilitiesMapper class provides specialized logic for extracting, transforming, and aggregating data from complex structures, including Pydantic models and standard Python mappings.
Core Mapping Functions
The mapper supports recursive deep equality checks, property accessors, and numeric aggregations. It integrates with the r[T] railway result pattern to ensure safe execution of transformations.
Sources: src/flext_core/_utilities/mapper.py:22-25
The diagram shows the pipeline of data transformation within the Mapper utility.
Sources: src/flext_core/_utilities/mapper.py:108-142
Key Mapper Operations
| Method | Description | Return Type |
|---|---|---|
agg | Aggregates numeric fields from a sequence of objects or mappings. | t.Numeric |
deep_eq | Performs recursive deep equality for nested dicts/lists/primitives. | bool |
prop | Returns an accessor function for extracting a specific property. | Callable |
transform | Applies a pipeline of filters and normalizations to a mapping. | p.Result[t.JsonMapping] |
| Sources: src/flext_core/_utilities/mapper.py:25-142 |
Project Metadata Discovery
The FlextUtilitiesProjectMetadata module is responsible for reading and deriving information about the project environment, primarily from pyproject.toml and installed distribution metadata.
Metadata Flow
The utility derives project constants and lazy alias metadata required for the framework's facade system. It ensures that package names, versions, and authors are correctly synchronized across the application.
Sources: tests/unit/test_utilities_project_metadata.py:15-26
Visual representation of project metadata derivation and alias loading.
Sources: tests/unit/test_utilities_project_metadata.py:46-105
Function Definitions
load_pyproject_toml(root): Parses the rawpyproject.tomlfile. RaisesFileNotFoundErrorif the file is absent.derive_project_constants(root): DerivesPACKAGE_NAME,CLASS_STEM, andSCAN_DIRECTORIESfrom a valid package root.read_lazy_alias_metadata(dist_name): Returns a table of runtime aliases (e.g.,c,m,p,u) for an installed distribution.
Sources: tests/unit/test_utilities_project_metadata.py:46-95
Foundation Utilities
The framework includes a set of low-level utilities for identifier generation and basic string validation, often used in end-to-end integration scenarios.
System Utilities
These are commonly accessed through the u facade in integration tests and production services.
Sources: tests/integration/test_system.py:180-210
| Feature | implementation | Description |
|---|---|---|
| UUID Generation | u.generate() | Returns a unique 36-character UUID string. |
| Timestamping | u.generate_iso_timestamp() | Returns a non-empty ISO-formatted timestamp string. |
| String Validation | u.string_non_empty(val) | Validates that a string contains non-whitespace content. |
| Sources: tests/integration/test_system.py:182-205 |
Framework Typing Integration
The utility layer is strictly typed and integrated into the generated root type-checking exports. This allows the framework to provide autocomplete and static analysis for all utility functions.
Class relationship showing how different utility modules are composed into the main facade.
Sources: src/flext_core/_root_typing_parts/utilities.py:1-50, src/flext_core/_root_typing.py:126
Summary
General Framework Utilities serve as the operational backbone for FLEXT-Core, providing the necessary tools for data transformation, project introspection, and basic system operations. By centralizing these functions into a structured utility layer, the framework ensures consistency across all enterprise modules and maintains compatibility with Python 3.13+ clean architecture standards.
Sources: README.md:8-10, examples/README.md:38-41