Configuration & Settings

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_api/_utilities/settings_manager.py
• src/flext_api/constants.py (Derived from history.json ChangeSet)
• src/flext_api/typings.py (Derived from history.json ChangeSet)
• pyproject.toml
• src/README.md
• examples/01_basic_usage.py

The configuration and settings system in the FLEXT API library provides a robust, type-safe framework for managing HTTP client parameters and application-wide constants. Built on Pydantic 2 patterns and Clean Architecture principles, the system ensures that configuration data is validated, normalized, and immutable throughout the application lifecycle.

Sources: src/README.md, src/flext_api/history.json (constants.py ChangeSet), pyproject.toml

Settings Architecture

The architecture separates configuration into domain-specific constants, environment-based settings, and a specialized utility manager for HTTP clients. This modular approach allows for strict validation while maintaining flexibility for different execution environments.

Core Configuration Components

Component	Description	File Path
Settings Manager	Domain-agnostic utility for validating and building HTTP client configurations.	src/flext_api/_utilities/settings_manager.py
Constants	Pure constant definitions using StrEnum and logical grouping.	src/flext_api/constants.py
Pydantic Settings	Environment variable management via pydantic-settings.	pyproject.toml
Infrastructure Settings	External concerns and environment-specific overrides.	src/flext_api/infrastructure/settings.py

Sources: src/README.md:14-34, src/flext_api/_utilities/settings_manager.py:16-25, pyproject.toml:34

Configuration Flow

The following diagram illustrates how raw configuration data is processed and converted into a validated ClientConfig model.

The flow demonstrates the transition from a standard dictionary or mapping to a structured Pydantic model with railway-oriented error handling.
Sources: src/flext_api/_utilities/settings_manager.py:80-128

Settings Management Logic

The FlextApiUtilitiesSettingsManager is the primary logic engine for HTTP configuration. It employs a "no fallback" policy for validated settings, ensuring that the application either has a valid state or explicitly fails.

Normalization and Validation

The manager handles complex types like headers by attempting to parse them from JSON strings or direct mappings. Boolean flags such as verify_ssl and log_requests are strictly validated using boolean adapters.

def _normalize_value(self, key: str, *, value: t.Scalar) -> p.Result[t.JsonPayload]:
    match key:
        case "headers" if isinstance(value, Mapping):
            # Validates mapping through STR_MAPPING_ADAPTER
            ...
        case "log_requests" | "log_responses" | "verify_ssl":
            # Validates using bool_adapter
            ...

Sources: src/flext_api/_utilities/settings_manager.py:61-78

Domain Constants

Constants are organized into nested classes within the FlextApiConstants (aliased as c) namespace. This allows for type-safe access to HTTP methods, status codes, and protocol-specific parameters.

HTTP and Protocol Constants

The library utilizes StrEnum for automatic Pydantic validation of HTTP methods and statuses.

Constant Group	Examples	Description
Method	GET, POST, PUT, DELETE	Standard HTTP methods.
ProtocolMethod	WS, SSE, GRAPHQL	Pseudo-HTTP methods for specialized handlers.
ContentType	JSON, XML, TEXT, FORM	Supported MIME types.
HTTP.Protocol	http/1.1, http/2, http/3	Supported network protocols.

Sources: src/flext_api/history.json (constants.py ChangeSet)

Global Validation Limits

The system enforces strict limits on configuration values to prevent malformed requests or resource exhaustion.

VALIDATION_LIMITS: Final[Mapping[str, t.Numeric]] = MappingProxyType({
    "MAX_URL_LENGTH": 2048,
    "MIN_TIMEOUT": 0.1,
    "MAX_TIMEOUT": 300.0,
    "MIN_RETRIES": 0,
    "MAX_RETRIES": 10,
})

Sources: src/flext_api/history.json (constants.py ChangeSet)

Type-Safe Settings Models

The system defines specialized types and adapters to ensure configuration integrity across the project. These are consolidated within the FlextApiTypes namespace.

The diagram shows the relationship between the manager utility and the immutable configuration model.
Sources: src/flext_api/_utilities/settings_manager.py:20-59, src/flext_api/history.json (typings.py ChangeSet)

Configuration Defaults

When values are not provided, the manager pulls defaults from the FlextApiConstants.

• Default Base URL: http://localhost:8000
• Default Timeout: Derived from FlextWebConstants.DEFAULT_TIMEOUT_SECONDS.
• Max Retries: Default defined in c.MAX_RETRY_ATTEMPTS.

Sources: src/flext_api/_utilities/settings_manager.py:95-128, src/flext_api/history.json (constants.py ChangeSet)

Conclusion

The FLEXT API configuration system provides a centralized and strictly validated foundation for all API operations. By combining Pydantic's powerful validation with Clean Architecture's separation of concerns, the library ensures that settings remain predictable and type-safe from initialization through execution.