Pydantic 2.11 Standardization
Relevant source files
The following files were used as context for generating this wiki page:
Pydantic 2.11 standardization within the flext-web project establishes a unified, type-safe framework for data validation and configuration management. By leveraging the latest features of Pydantic v2, the project ensures rigorous enforcement of data schemas across the entire platform, providing a "Zero Tolerance" approach to type safety. This standardization is central to the project's Unified Models Pattern, which consolidates request and response structures into cohesive namespaces.
The scope of this standardization includes core model definitions, settings management via pydantic-settings, and integration with static analysis tools like MyPy. This ensures that every component in the flext-web ecosystem—from internal services to public API facades—operates on a shared, validated data foundation.
Sources: pyproject.toml:95-97, guides/development.md:126-140, development.md:21-26
Architecture and Core Components
The standardization architecture is built upon the pydantic>=2.13.3 core library, supplemented by pydantic-settings for environment-aware configuration. The system utilizes a hierarchical model structure where base models provide common functionality, and specific project models extend these for domain-specific needs.
Component Relationship
The following diagram illustrates how Pydantic models interact with the framework's configuration and service layers.
The validation layer acts as a gateway, ensuring that data entering the system from environment variables or configuration files strictly adheres to defined schemas before reaching service logic.
Sources: pyproject.toml:95-97, guides/configuration.md:28-36, development.md:14-20
Configuration Management
Standardization requires that all configuration access is namespaced and direct. The project uses pydantic-settings to load configuration from multiple sources, prioritizing them in a specific order: defaults, environment variables, configuration files, and finally programmatic overrides.
Configuration Sources and Priority
| Priority | Source | Description |
|---|---|---|
| 1 | Programmatic | Direct instantiation in code. |
| 2 | Config Files | YAML, JSON, or TOML files. |
| 3 | Environment | Variables prefixed with FLEXT_. |
| 4 | Defaults | Values defined in the Pydantic model. |
| Sources: guides/configuration.md:28-36, development.md:41-48 |
Implementation Pattern
Configurations are defined using a namespaced singleton pattern. This allows for runtime settings that are both typed and validated.
from flext_web import FlextWebSettings, settings
runtime_settings = FlextWebSettings(
Web={"host": "localhost", "port": 8080}, debug=settings.debug
)
Sources: development.md:41-48, guides/configuration.md:139-152
Data Modeling Standards
The project enforces the Unified Models Pattern, where models are organized within project-specific namespaces to avoid scattered definitions. This is critical for maintaining a clean architecture and ensuring consistent API contracts.
Model Categories
| Category | Base Class | Purpose |
|---|---|---|
| Request | m.BaseModel | Validates incoming API payloads. |
| Response | m.BaseModel | Ensures outgoing data matches the public contract. |
| Config | pydantic_settings.BaseSettings | Manages environment-aware settings. |
| Entities | m.BaseModel | Represents core domain data structures. |
| Sources: guides/development.md:144-156, development.md:14-20, pyproject.toml:97 |
Validation Logic Flow
The flow of data through Pydantic validation ensures that logic only proceeds if the data is structurally sound.
Tooling and Quality Gates
Standardization is enforced through automated quality gates and specific IDE/Linter configurations. The project uses mypy with the pydantic.mypy plugin to provide static type checking for models.
Static Analysis Configuration
The pyproject.toml defines strict rules for the Pydantic MyPy plugin to prevent common pitfalls such as untyped fields or missing dynamic aliases.
| Option | Value | Description |
|---|---|---|
init_forbid_extra | true | Prevents passing unknown arguments to model __init__. |
init_typed | true | Enforces type checking on __init__ arguments. |
warn_untyped_fields | true | Flags fields defined without explicit type annotations. |
| Sources: pyproject.toml:139-144 |
Automation Skills
The project includes a dedicated "Pydantic v2 Policy Gate" skill. This skill uses ast-grep rules to detect and enforce Pydantic v2 patterns across the codebase, ensuring that migrations from v1 or non-standard patterns are blocked.
Sources: guides/skill-automation-pattern.md:65-71
Conclusion
Pydantic 2.11 Standardization is a cornerstone of the flext-web architecture, providing the technical foundation for type-safe, enterprise-grade web services. By centralizing models, enforcing strict validation through quality gates, and using pydantic-settings for configuration, the project maintains a high-quality, predictable codebase that facilitates rapid development and robust data handling.
Sources: guides/development.md:73-77, development.md:58-65