Client & Codec Utilities
Relevant source files
The following files were used as context for generating this wiki page:
The Client & Codec Utilities module provides the foundational infrastructure for HTTP communication, data serialization, and request normalization within the FLEXT API. This system is designed to handle high-performance REST operations by providing specialized mixins for codec handling and request preparation, ensuring that all network interactions adhere to the project's strict typing and validation standards.
At its core, the module facilitates the conversion between internal domain models and wire-format representations (such as JSON, MessagePack, or CBOR). It manages the lifecycle of HTTP requests through a plugin-based architecture, allowing for extensible behavior in request construction and response parsing.
Sources: src/README.md, src/flext_api/_utilities/init.py
Architecture and Components
The utility layer is structured as a collection of specialized classes and mixins that are lazily loaded to optimize startup performance. The main components include the FlextApiClient, which aggregates functionality from various mixins to provide a unified interface for HTTP operations.
Component Relationship
The following diagram illustrates how the different utility components interact to process an API request:
The diagram shows the flow from high-level request normalization to low-level serialization and network transport.
Sources: src/flext_api/_utilities/init.py, src/README.md
Key Utility Modules
| Module | Purpose |
|---|---|
client.py | Main HTTP client implementation with plugin support. |
client_codec.py | Mixin for encoding request bodies and decoding responses. |
request_utils.py | Static utilities for payload normalization and timeout coercion. |
serializers.py | Low-level implementations for JSON, MessagePack, and CBOR. |
constants.py | Centralized StrEnum definitions for methods, status codes, and types. |
Sources: src/flext_api/_utilities/init.py, src/flext_api/constants.py
Codec and Serialization
The FlextApiClientCodecMixin handles the transformation of data between Python objects and various serialization formats. It supports multiple formats defined in HttpSerializationFormat, including standard JSON and high-performance binary formats.
Supported Serialization Formats
The system utilizes StrEnum for type-safe format selection, ensuring Pydantic validation at the boundary.
- JSON: The default format for web compatibility.
- MSGPACK: High-performance binary serialization.
- CBOR: Concise Binary Object Representation.
- CUSTOM: Extensibility point for user-defined codecs.
Sources: src/flext_api/constants.py:165-175, src/flext_api/_utilities/client_codec.py
Data Transformation Flow
This sequence shows the bidirectional flow of data through the codec layer.
Sources: src/flext_api/_utilities/client_codec.py, src/flext_api/_utilities/serializers.py
Request Normalization and Utilities
The FlextApiUtilitiesRequestUtils provides static methods to ensure that request data is consistent before it reaches the transport layer. This includes path normalization, query parameter formatting, and strict timeout validation.
Request Payload Construction
The build_request_payload function is a critical entry point that aggregates various request components into a validated structure.
# Example of normalized request construction
payload_result = u.Api.RequestUtils.build_request_payload(
method=c.Api.Method.GET,
url=f"{self.settings.base_url.rstrip('/')}/resources",
headers={"accept": c.Api.ContentType.JSON.value},
request_kwargs={"params": {"page": 1, "active": True}},
timeout=timeout_result.value,
)
Sources: examples/01_basic_usage.py:29-35, src/flext_api/_utilities/request_utils.py
Timeout Coercion
The system enforces positive timeouts using coerce_positive_timeout, converting string or numeric inputs into a validated float or raising an error if the value is non-positive or malformed.
Sources: examples/01_basic_usage.py:22-24, src/flext_api/constants.py:218-224
Constants and Type Definitions
The utilities rely on a centralized namespace of constants and types that extend the core flext library. These are organized into nested classes for logical grouping.
API Method Enums
HTTP methods are defined using StrEnum to provide automatic Pydantic 2 validation and string serialization.
| Enum Member | Wire Value | Type |
|---|---|---|
Method.GET | "GET" | Safe, Idempotent |
Method.POST | "POST" | Unsafe, Non-idempotent |
Method.PUT | "PUT" | Unsafe, Idempotent |
Method.DELETE | "DELETE" | Unsafe, Idempotent |
ProtocolMethod.WS | "WS" | Pseudo-method for WebSockets |
Sources: src/flext_api/constants.py:44-78, src/flext_api/typings.py:38-42
Type Aliases
The module uses PEP 695 type aliases for strict interface definitions.
WebHeaders:t.ScalarOrStrSequenceMappingWebParams:t.MappingKV[str, str | t.StrSequence]RequestBody:t.JsonMapping | str | t.StrictBytes
Sources: src/flext_api/typings.py:44-48
Conclusion
The Client & Codec Utilities form the backbone of the FLEXT API's data handling capabilities. By combining strict type validation, flexible serialization via ClientCodecMixin, and robust request normalization through RequestUtils, the system ensures high-performance and reliable HTTP communication. The use of lazy loading for these utilities ensures that the library remains lightweight while providing comprehensive features for enterprise-grade API interactions.