Settings and Configuration

Relevant source files

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

• src/flext_core/settings.py
• src/flext_core/config.py
• src/flext_core/_utilities/settings.py
• tests/unit/test_settings.py
• tests/integration/test_settings_integration.py
• tests/unit/test_utilities_settings_coverage_100.py
• tests/unit/test_utilities_config.py

The Settings and Configuration system in FLEXT-Core provides an enterprise-grade foundation for managing application state, environment variables, and runtime parameters. It leverages Pydantic-based models to ensure strict validation, type safety, and centralized access through a singleton pattern. The system is designed for modern Python 3.13 environments, adhering to Clean Architecture principles by separating configuration loading from application logic.

This module encompasses global runtime settings (e.g., debug modes, logging levels), environment variable resolution, and declarative configuration primitives. It serves as the primary source of truth for all modules within the FLEXT ecosystem, facilitating consistent behavior across different environments.
Sources: README.md:12-18, tests/unit/test_settings.py:1-7, tests/integration/test_settings_integration.py:1-6

Runtime Settings (FlextSettings)

The FlextSettings class is the central facade for application configuration. It manages a set of universal scalar fields that control the core behavior of the framework.

Singleton Management

The system implements a singleton pattern to ensure that all components access the same configuration state. This instance can be retrieved, updated, or reset, specifically to facilitate isolated testing.

The flow describes the lifecycle of the global settings instance, from initialization via fetch_global to state modifications using update_global and cleanup through reset_for_testing.
Sources: tests/unit/test_settings.py:17-43, tests/integration/test_settings_integration.py:22-38

Configuration Fields

The following universal runtime fields are supported by default:

Field Name	Type	Default Value	Description
debug	bool	False	Enables debug mode for the application.
trace	bool	False	Enables detailed tracing. Requires debug=True.
log_level	str	INFO	Canonical log level (DEBUG, INFO, etc.).
timezone	str	UTC	The application's default timezone.
async_logging	bool	True	Determines if logging operations are asynchronous.

Sources: tests/unit/test_settings.py:30-38, tests/integration/test_settings_integration.py:46-52

Configuration Loading and Environment Resolution

FLEXT-Core uses a tiered approach to resolve configuration, prioritizing environment variables and local .env files over code-defined defaults.

Environment Variable Precedence

Environment variables prefixed with FLEXT_ automatically override the default values in FlextSettings. For example, FLEXT_LOG_LEVEL will override the log_level field.
Sources: tests/integration/test_settings_integration.py:64-70, README.md:27

Env File Resolution

The utility u.resolve_env_file() determines which environment file to load based on the following priority:

1. Override: A file path provided via the FLEXT_ENV_FILE environment variable.
2. CWD Default: A file named .env located in the current working directory.
3. Fallback: The default filename .env.

Sources: tests/unit/test_utilities_settings_coverage_100.py:100-116

Log Level Resolution Logic

The system applies specific logic to derive the effective log level based on the trace and debug flags, ensuring that development modes take precedence over explicit requests.

The diagram shows the logic within u.resolve_effective_log_level, where trace forces DEBUG and debug caps the level at INFO if a higher level was requested.
Sources: tests/unit/test_utilities_settings_coverage_100.py:53-76

Declarative Configuration Primitives

FLEXT-Core provides low-level utilities for handling TOML configurations and performing deep merges or environment variable expansions within dictionaries.

Configuration Utilities

• config_load: Parses TOML files into mappings. It is designed to "fail closed," returning failure results for missing or malformed files.
• config_merge: Performs a deep merge of two dictionaries, combining nested structures rather than simply overwriting top-level keys.
• config_env_override: Recursively traverses a configuration mapping and expands strings containing ${VAR} or ${VAR:-default} using provided environment values.

Sources: tests/unit/test_utilities_config.py:22-120

Environment Expansion Examples

The config_env_override utility supports complex fallback chains:

• ${HOME}/path expands to /tmp/path if HOME=/tmp.
• ${PORT:-8080} uses 8080 if PORT is unset.
• Nested fallbacks: ${A:-${B:-default}} resolves through a chain of variables.

Sources: tests/unit/test_utilities_config.py:73-120

Testing and Lifecycle Support

To support reliable integration testing, FlextSettings includes mechanisms to isolate global state.

• reset_for_testing(): Purges the global singleton, forcing a fresh load from environment variables on the next access.
• singleton_disabled(): A context manager (used in tests) to instantiate FlextSettings objects without affecting the global singleton.
• clone(overrides=...): Creates an independent copy of a settings instance with specific modifications, ensuring the source remains immutable.

Sources: tests/unit/test_settings.py:46-72, tests/integration/test_settings_integration.py:84-90

Conclusion

The Settings and Configuration system in FLEXT-Core ensures that enterprise applications remain configurable and observable. By combining Pydantic's strict validation with a robust singleton lifecycle and flexible environment resolution, the framework provides a predictable environment for both development and production workloads. The use of declarative primitives and deep-merge capabilities further allows for complex, hierarchical configuration management across the ecosystem.