Type System & Strict Typing
Relevant source files
The following files were used as context for generating this wiki page:
The FLEXT API type system is designed around the principles of "Strict, Most-Restrictive Typing" and Clean Architecture. It leverages advanced Python 3.13+ features—including PEP 695 type aliases and StrEnum—to ensure a single source of truth (SSOT) for all domain-specific data structures. The system is architected to eliminate weak types, aliases, and loosely-typed escape hatches like Any or bare object.
By consolidating type definitions within a unified namespace (FlextApiTypes), the project enforces consistent validation across the API, Web, and Core layers. This strictness is enforced by a multi-layered toolchain including Mypy, Pyright, and Pydantic 2, ensuring that all data moving through the system adheres to documented contracts.
Sources: AGENTS.md:86-88, src/flext_api/typings.py:1-12
Core Typing Architecture
The type system is structured as a class-based hierarchy that extends base types from flext-core and flext-web. This inheritance model allows the API layer to specialize types while maintaining compatibility with the broader ecosystem.
Type Hierarchy and MRO
The central entry point for types is FlextApiTypes, which inherits from FlextWebTypes. This creates a Method Resolution Order (MRO) that cascades from Core to Web to API.
Domain-Specific Type Aliases
FLEXT API uses PEP 695 type statements to define strict aliases for HTTP-related structures. These definitions prevent "type switching" defects and ensure that function signatures are descriptive and restrictive.
| Alias | Base Type | Description |
|---|---|---|
WebHeaders | t.ScalarOrStrSequenceMapping | Mapping of HTTP header keys to values or sequences. |
WebParams | t.MappingKV[str, str | t.StrSequence] | Query parameter mapping. |
RequestBody | t.JsonValue | t.StrictBytes | Union for incoming payload data. |
ResponseBody | t.JsonValue | t.StrictBytes | None | Union for outgoing payload data. |
HttpResponseDict | t.MappingKV[...] | Dictionary representation of a complete HTTP response. |
RouteData | t.MappingKV[...] | Structure used for internal route registration. |
Sources: src/flext_api/typings.py:28-48, src/flext_api/history.json:ChangeSet_Writing_typings.py:line_30-50
Validation and Serialization via TypeAdapters
To bridge the gap between static typing and runtime validation, the system employs Pydantic TypeAdapter instances. These adapters are pre-configured for standard API primitives and complex structures, facilitating zero-cost validation at the boundaries of the application.
# src/flext_api/typings.py:59-71
API_JSON_VALUE_ADAPTER: u.TypeAdapter[t.JsonValue] = t.json_value_adapter()
BINARY_CONTENT_ADAPTER: u.TypeAdapter[t.StrictBytes] = t.binary_content_adapter()
HOSTNAME_ADAPTER: u.TypeAdapter[t.HostnameStr] = t.hostname_str_adapter()
PORT_NUMBER_ADAPTER: u.TypeAdapter[t.PortNumber] = t.port_number_adapter()
REQUEST_BODY_ADAPTER: u.TypeAdapter[RequestBody] = u.TypeAdapter(RequestBody)
Sources: src/flext_api/typings.py:59-79
Data Flow for Validation
The following diagram illustrates how raw input data is processed through TypeAdapters to reach a strictly typed state.
Type-Safe Constants (StrEnum)
The project enforces strict typing even for constants by using StrEnum with Pydantic 2 integration. This pattern ensures that values like HTTP methods and status codes are not just strings, but members of a validated set.
API Method Enumeration
HTTP methods are defined within FlextApiConstants.Api.Method. Using StrEnum allows these to be accepted as either the enum member or a valid string during Pydantic model instantiation.
# src/flext_api/history.json (ChangeSet: Writing file <constants.py>)
@unique
class Method(StrEnum):
GET = "GET"
POST = "POST"
PUT = "PUT"
DELETE = "DELETE"
# ... other methods
Sources: src/flext_api/history.json:ChangeSet_Writing_constants.py:line_39-55
Protocol-Specific Methods
Special handlers for non-standard HTTP protocols are also typed strictly:
- WS: WebSocket
- SSE: Server-Sent Events
- GRAPHQL: GraphQL operations
Sources: src/flext_api/history.json:ChangeSet_Writing_constants.py:line_61-75
Strict Tooling Configuration
The type system is enforced through a rigid configuration in pyproject.toml. The project requires Python 3.13 and uses "strict" mode for Pyright and specific plugins for Mypy.
| Tool | Key Configurations |
|---|---|
| Mypy | strict_equality = true, warn_unreachable = true, check_untyped_defs = true |
| Pyright | typeCheckingMode = "strict", reportUnnecessaryCast = "error" |
| Pydantic-Mypy | init_forbid_extra = true, init_typed = true |
| Coverage | Excludes if TYPE_CHECKING: blocks from metrics |
Sources: pyproject.toml:130-153, pyproject.toml:158-164, pyproject.toml:281-295
Conclusion
The FLEXT API type system serves as the foundational "engineering law" of the repository. By prohibiting Any, requiring explicit TypeAdapter usage, and leveraging the latest Python typing features, the system ensures that the code remains self-documenting, maintainable, and resilient to runtime errors.
Sources: AGENTS.md:16-20, src/flext_api/typings.py:1-8