Pydantic Integration
Relevant source files
The following files were used as context for generating this wiki page:
Pydantic Integration in the flext-api project serves as the backbone for data validation, settings management, and type-safe communication. By leveraging Pydantic 2, the system ensures that all inbound HTTP requests, internal domain entities, and outbound responses adhere to strict schemas. This integration facilitates a "Zero-Debt" baseline where validation occurs at the boundaries of the application, preventing malformed data from reaching the core business logic.
The architecture utilizes Pydantic for three primary purposes: configuration management through pydantic-settings, runtime data validation via TypeAdapter and model_validate, and type-safe enumerations using StrEnum which Pydantic handles automatically. This structured approach allows for a "railway" result contract, where validation failures are captured as explicit error objects rather than unhandled exceptions.
Sources: pyproject.toml:35-37, examples/01_basic_usage.py:17-21, src/flext_api/history.json:ChangeSet_Writing_file_constants.py
Dependency Architecture
The project explicitly requires Pydantic v2 and its related ecosystem components to support modern Python 3.13 features.
| Dependency | Minimum Version | Purpose |
|---|---|---|
pydantic | >=2.13.3 | Core data validation and settings |
pydantic-core | >=2.46.3 | High-performance Rust-based validation core |
pydantic-settings | >=2.14.0 | Environment-based configuration management |
Sources: pyproject.toml:35-37
Type-Safe Constants and Enums
FLEXT API uses enum.StrEnum combined with Pydantic patterns to create single sources of truth for domain constants. These enums are designed for automatic Pydantic validation within models.
HTTP Method Validation
The Method enum defines valid HTTP verbs. When used in a Pydantic model, it automatically rejects invalid strings and serializes them correctly to JSON.
@unique
class Method(StrEnum):
GET = "GET"
POST = "POST"
# ... other methods
Sources: src/flext_api/history.json:ChangeSet_Writing_file_constants.py:lines_42-65
Validation Logic Flow
The following diagram illustrates how constants interact with Pydantic validation during the request lifecycle.
The system ensures that pseudo-methods like WS, SSE, and GRAPHQL are handled separately from standard HTTP methods through ProtocolMethod enums.
Sources: src/flext_api/history.json:ChangeSet_Writing_file_constants.py:lines_67-83
Unified Type Adapters
A central component of the integration is the FlextApiTypes class, which exposes pre-configured TypeAdapter instances. These adapters allow for validating data without necessarily instantiating a full Pydantic model, providing performance benefits for simple types and complex mappings.
Key Type Adapters
| Adapter Name | Target Type | Usage |
|---|---|---|
API_JSON_VALUE_ADAPTER | t.JsonValue | Validates arbitrary JSON data structures |
REQUEST_BODY_ADAPTER | RequestBody | Handles JSON mappings, strings, or bytes |
HOSTNAME_ADAPTER | t.HostnameStr | Validates RFC-compliant hostnames |
PORT_NUMBER_ADAPTER | t.PortNumber | Validates integer range 1-65535 |
Sources: src/flext_api/history.json:ChangeSet_Writing_file_typings.py:lines_70-120
Model Validation Patterns
The system promotes explicit validation using the u.parse_model utility, which wraps Pydantic's internal validation to return a p.Result object. This ensures that validation errors are treated as data rather than control flow interruptions.
Sequence of Validation in 01_basic_usage.py
The basic usage flow demonstrates how a request is normalized and then validated against a Pydantic model.
Storage and Metadata Models
Pydantic models are used to structure internal storage states and metadata, ensuring consistency in how cache entries and statistics are tracked.
Storage Components
- m.Api.Storage.Settings: Configures namespaces and TTL values.
- m.Api.Storage.Metadata: Wraps stored values with timestamps and TTL.
- m.Api.Storage.State: Tracks a map of entries and operation counters.
- m.Api.Storage.Stats: Provides a summarized view of storage health, including
memory_usageandcache_hits.
Sources: examples/01_basic_usage.py:108-132
Tooling and Quality Gates
The Pydantic integration is protected by strict static analysis and testing requirements defined in pyproject.toml.
- Mypy Plugin: Uses
pydantic.mypyto ensure field types are correctly inferred during development. - Validation Limits: Global constants like
MAX_URL_LENGTH(2048) andVALIDATION_LIMITSmapping (timeout, retries) are enforced through Pydantic models. - Unit Tests: Files like
test_fields_core.pyandtest_types_core.pyspecifically validate Pydantic integration points.
Sources: pyproject.toml:173, 191-196, src/README.md:lines_88-90, src/flext_api/history.json:ChangeSet_Writing_file_constants.py:lines_200, 246-252
Pydantic Integration in flext-api provides the necessary rigor for building high-performance APIs by ensuring every data point is typed, validated, and documented through code.