Settings Management

Relevant source files

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

• guides/configuration.md
• configuration/README.md
• development.md
• troubleshooting.md
• pyproject.toml
• guides/development.md

Settings Management in flext-web provides a robust, type-safe configuration system built on Pydantic v2. It centralizes application parameters into a validated singleton, ensuring that all components within the web interface operate with consistent and verified configuration data. The system supports hierarchical loading from multiple sources including defaults, environment variables, and configuration files.

The architecture is centered around a canonical public facade (web) and a namespaced settings singleton (settings.Web). This design allows for direct access to runtime values while maintaining strict validation boundaries for overrides and programmatic configuration.
Sources: configuration/README.md:1-10, development.md:12-20, guides/configuration.md:30-35

Architecture and Components

The flext-web settings architecture follows a singleton pattern where configuration is namespaced and direct. The core model, FlextWebSettings, inherits from the foundational FlextSettings class provided by flext-core.

The Settings Singleton

Configuration access is direct through the package root. Operational code is encouraged to use the settings.Web instance for live values rather than re-instantiating settings classes.

This diagram illustrates the relationship between the public singleton and the underlying validated models.
Sources: development.md:37-43, configuration/README.md:13-18

Hierarchical Loading

flext-web loads configuration using a specific order of precedence where later sources override earlier ones. This allows developers to set sensible defaults that can be customized for different environments.

The flow shows how configuration values are merged, with Programmatic Configuration having the highest priority.
Sources: guides/configuration.md:36-41

Configuration Models and Fields

The primary model for the web interface is FlextWebSettings. It encapsulates both universal fields (like debug) and web-specific fields (within the Web namespace).

Core Settings Fields

The following table outlines the primary configuration fields managed by FlextWebSettings:

Field Name	Type	Description	Namespace
app_name	str	Name of the web application	Web
host	str	Bind address for the server	Web
port	int	Port number for the server	Web
debug	bool	Enables debug mode and detailed logging	Root
secret_key	str	Cryptographic key for session security	Web
ssl_enabled	bool	Whether to enable TLS/SSL	Web
ssl_cert_path	str	Path to the SSL certificate file	Web
ssl_key_path	str	Path to the SSL private key file	Web

Sources: configuration/README.md:34-45, guides/configuration.md:47-65

Validation Logic

All settings are validated at the "facade-MRO boundary" using Pydantic. Validation includes type checking, range checks (e.g., ports must be positive), and presence checks for required strings.

from flext_web import FlextWebSettings, u

# Example of boundary validation
runtime_settings = FlextWebSettings(
    Web={
        "host": "localhost",
        "port": 8080,
        "secret_key": "development-secret-key-32-characters-long",
    }
)
assert u.Web.validate_settings(runtime_settings).unwrap()

Sources: configuration/README.md:52-64, troubleshooting.md:20-27

Environment Variables

The system automatically maps environment variables to the settings model using the prefix FLEXT_WEB_. Double underscores are used to represent nested namespaces.

Environment Variable	Mapping
FLEXT_WEB_DEBUG	settings.debug
FLEXT_WEB_WEB__HOST	settings.Web.host
FLEXT_WEB_WEB__PORT	settings.Web.port
FLEXT_WEB_WEB__SECRET_KEY	settings.Web.secret_key
FLEXT_WEB_WEB__SSL_ENABLED	settings.Web.ssl_enabled

Sources: configuration/README.md:73-83, guides/configuration.md:42-55

Implementation Rules and Best Practices

To maintain the integrity of the configuration system, several operational rules are enforced:

1. Namespaced Access: Always prefer from flext_web import settings for accessing live values.
2. Secret Handling: Never store secrets in configuration files; use environment variables (e.g., FLEXT_WEB_WEB__SECRET_KEY).
3. Boundary Validation: Use FlextWebSettings for explicit validated overrides when starting services or testing.
4. No Parallel Helpers: Do not create parallel settings helpers or bypass the Pydantic models. Obsolete methods like get_web_settings or reset_web_settings are strictly prohibited.
5. Type Safety: MyPy strict mode and Pyrefly are used to ensure that settings injection remains type-safe across the project.

This diagram demonstrates the sequence of validating settings before service bootstrap.
Sources: configuration.md:90-105, development.md:46-52, configuration/README.md:104-108, guides/development.md:120-130

Summary

Settings Management in flext_web ensures that the platform remains stable and predictable by enforcing strict validation rules and a clear hierarchy of configuration sources. By utilizing Pydantic v2 and a centralized singleton, the system provides developers with a consistent interface for managing everything from server network parameters to security credentials, while preventing common configuration errors through early boundary validation.