Config Class

Main Config class β€” assembles all mixin capabilities.

This module defines the Config class which inherits from focused mixin classes to keep the codebase modular while presenting a single public API.

Mixins:

  • ConfigLoading: load, reload, merge, file watch, hooks

  • ConfigAccess: get, set, keys, has, schema, explain, diff, layers

  • ConfigDebug: source tracking, debug reports, conflict detection

  • ConfigObservabilityMixin: metrics, events, versioning

  • ConfigValidation: Pydantic and JSON Schema validation

class confii.config.Config(env: str | None = None, env_switcher: Any = <object object>, loaders: Sequence[Loader] | None = None, dynamic_reloading: bool | None = None, use_env_expander: Any = <object object>, use_type_casting: Any = <object object>, enable_ide_support: Any = <object object>, ide_stub_path: Any = <object object>, debug_mode: Any = <object object>, deep_merge: Any = <object object>, merge_strategy: Any = <object object>, merge_strategy_map: Any = <object object>, env_prefix: Any = <object object>, sysenv_fallback: Any = <object object>, secret_resolver: Any | None = None, schema: Any | None = None, schema_path: Any = <object object>, validate_on_load: Any = <object object>, strict_validation: Any = <object object>, freeze_on_load: Any = <object object>, on_error: Any = <object object>)[source]

Bases: Generic[T], ConfigLoading, ConfigAccess, ConfigDebug, ConfigObservabilityMixin, ConfigValidation

Main configuration management class for Confii.

Supports generic typing for full IDE autocomplete and mypy support when used with a Pydantic model schema:

config = Config[AppConfig](

loaders=[YamlLoader(β€œconfig.yaml”)], schema=AppConfig, validate_on_load=True,

) config.typed.database.host # IDE knows this is str config.typed.database.port # IDE knows this is int

Without a type parameter, Config works as an untyped config object with dynamic attribute access (backward compatible):

config = Config(loaders=[YamlLoader(β€œconfig.yaml”)]) config.database.host # type: Any

Thread Safety:

  • reload() and set() are protected by an RLock, ensuring that concurrent mutations do not corrupt internal state.

  • __getattr__ (read access) is safe to call concurrently from multiple threads without external synchronisation.

  • freeze() makes the config fully thread-safe by preventing all further writes.

  • File watcher callbacks run in a separate thread and are lock-protected, so reloads triggered by file changes are serialised.

  • HookProcessor uses its own RLock for thread-safe hook registration and execution.

Versioning:

This library follows Semantic Versioning. Pre-1.0 releases may include breaking changes in minor versions. Post-1.0, breaking changes will only occur in major versions with deprecation warnings in the prior minor release.

env

Current environment name

dynamic_reloading

Whether file watching is enabled

merged_config

The complete merged configuration dictionary

env_config

Environment-specific configuration

__getattr__(item: str) → Any[source]

Get configuration value using attribute-style access.

__init__(env: str | None = None, env_switcher: Any = <object object>, loaders: Sequence[Loader] | None = None, dynamic_reloading: bool | None = None, use_env_expander: Any = <object object>, use_type_casting: Any = <object object>, enable_ide_support: Any = <object object>, ide_stub_path: Any = <object object>, debug_mode: Any = <object object>, deep_merge: Any = <object object>, merge_strategy: Any = <object object>, merge_strategy_map: Any = <object object>, env_prefix: Any = <object object>, sysenv_fallback: Any = <object object>, secret_resolver: Any | None = None, schema: Any | None = None, schema_path: Any = <object object>, validate_on_load: Any = <object object>, strict_validation: Any = <object object>, freeze_on_load: Any = <object object>, on_error: Any = <object object>) → None[source]

Initialize the Config instance.

Parameters:

  • env – Environment name (e.g., β€˜development’, β€˜production’).

  • env_switcher – Name of an environment variable that controls the active environment. If set, the value of that env var overrides the env parameter. For example, Config(env_switcher="APP_ENV") reads os.environ["APP_ENV"] to determine which environment section to use.

  • loaders – List of configuration loaders.

  • dynamic_reloading – Enable file watching for config changes.

  • use_env_expander – Enable ${VAR} expansion in values.

  • use_type_casting – Enable automatic type casting.

  • enable_ide_support – Generate IDE type stubs (default: True).

  • ide_stub_path – Custom path for IDE stub file.

  • debug_mode – Enable detailed source tracking.

  • deep_merge – Enable deep merging of nested config (default: True).

  • merge_strategy – Default MergeStrategy for combining layers.

  • merge_strategy_map – Per-path merge strategy overrides.

  • env_prefix – Auto-add EnvironmentLoader with this prefix.

  • sysenv_fallback – If True, keys not found in file-based config will automatically fall back to environment variables. Uses env_prefix if set, otherwise matches the raw key name uppercased with dots replaced by underscores (e.g., database.host β†’ DATABASE_HOST).

  • secret_resolver – SecretResolver for ${secret:key} placeholders.

  • schema – Pydantic model or JSON Schema dict for validation.

  • validate_on_load – Validate immediately after loading.

  • strict_validation – Raise on validation failure (vs. warn).

Example

>>> from confii import Config
>>> from confii.loaders import YamlLoader
>>> config = Config(
...     env="production",
...     loaders=[YamlLoader("config.yaml")],
... )
static builder() → ConfigBuilder[source]

Create a new ConfigBuilder instance.

Returns:

New ConfigBuilder instance

Example

>>> config = Config.builder() \
...     .with_env("production") \
...     .add_loader(YamlLoader("config.yaml")) \
...     .build()
export(format: str = 'json', output_path: str | None = None) → str[source]

Export configuration in specified format.

Parameters:

  • format – Export format (β€˜json’, β€˜yaml’, β€˜toml’)

  • output_path – Optional path to save exported config

Returns:

Exported configuration as string

freeze() → None[source]

Freeze configuration β€” set() and reload() will raise.

get_source(key: str) → str | None[source]

Get the source file for a configuration key.

property is_frozen: bool

Whether this configuration is frozen (read-only).

property typed: T

Access configuration as a validated, fully-typed Pydantic model.

Returns the validated Pydantic model instance, giving you full IDE autocomplete and mypy/pyright type checking on every attribute access.

Requires schema to be a Pydantic model class and validate_on_load=True (or a prior call to validate()).

Returns:

The validated Pydantic model instance of type T.

Raises:

ValueError – If no schema was provided or validation hasn’t run.

Example

>>> from pydantic import BaseModel
>>> class AppConfig(BaseModel):
...     database_host: str
...     database_port: int = 5432
>>> config = Config[AppConfig](
...     loaders=[YamlLoader("config.yaml")],
...     schema=AppConfig,
...     validate_on_load=True,
... )
>>> config.typed.database_host  # IDE knows: str
>>> config.typed.database_port  # IDE knows: int