Module

config.unified_loader

Unified configuration loader for all config modes.

This module provides a single loader that handles both single-file and directory-based configuration. It replaces the previous ConfigLoader and ConfigDirectoryLoader classes with a unified implementation.

Precedence (lowest to highest):

  1. DEFAULTS (nested structure)
  2. User config (single file or directory)
  3. Environment overrides (optional)
  4. Profile overrides (optional)

See Also:

  • bengal.config.accessor: Config and ConfigSection classes.
  • bengal.config.defaults: Default configuration values.
  • bengal.config.validation: Configuration validation.
1Class

Classes

UnifiedConfigLoader 8 ▼
Single loader for all config modes. Precedence (lowest to highest): 1. DEFAULTS (nested struct…

Single loader for all config modes.

Precedence (lowest to highest): 1. DEFAULTS (nested structure) 2. User config (single file or directory) 3. Environment overrides (optional) 4. Profile overrides (optional)

Methods

load 3 Config ▼
Load configuration from site root. Auto-detects config mode: - config/ dir…
def load(self, site_root: Path, environment: str | None = None, profile: str | None = None) -> Config

Load configuration from site root.

Auto-detects config mode:

  • config/ directory exists → directory mode
  • bengal.toml/yaml exists → single-file mode
  • Neither → DEFAULTS only
Parameters
Name Type Description
site_root —

Root directory of the site.
environment —

Environment name (auto-detected if None).

Default:None
profile —

Profile name (optional).

Default:None
Returns
Config Config object with structured access.
get_origin_tracker 0 ConfigWithOrigin | None ▼
Get the origin tracker instance if tracking is enabled.
def get_origin_tracker(self) -> ConfigWithOrigin | None
Returns
ConfigWithOrigin | None
load_snapshot 3 ConfigSnapshot ▼
Load configuration and return a frozen ConfigSnapshot. This is the preferred e…
def load_snapshot(self, site_root: Path, environment: str | None = None, profile: str | None = None) -> ConfigSnapshot

Load configuration and return a frozen ConfigSnapshot.

This is the preferred entry point for RFC: Snapshot-Enabled v2. Returns a frozen, typed configuration that is thread-safe by construction.

Parameters
Name Type Description
site_root —

Root directory of the site.
environment —

Environment name (auto-detected if None).

Default:None
profile —

Profile name (optional).

Default:None
Returns
ConfigSnapshot Frozen ConfigSnapshot with typed sections.
Internal Methods 5 ▼
__init__ 1 ▼
Initialize the unified configuration loader.
def __init__(self, track_origins: bool = False) -> None
Parameters
Name Type Description
track_origins —

If True, track which file contributed each config key.

Default:False
_default_config 0 dict[str, Any] ▼
Return a deep copy of DEFAULTS for single-file parity with directory loader.
def _default_config(self) -> dict[str, Any]
Returns
dict[str, Any]
_find_config_file 1 Path | None ▼
Find single config file (bengal.toml, bengal.yaml, bengal.yml).
def _find_config_file(self, site_root: Path) -> Path | None
Parameters
Name Type Description
site_root —
Returns
Path | None
_load_file 1 dict[str, Any] ▼
Load a single config file (TOML or YAML).
def _load_file(self, path: Path) -> dict[str, Any]
Parameters
Name Type Description
path —
Returns
dict[str, Any]
_load_directory 1 dict[str, Any] ▼
Load all YAML files from config/_default/ directory.
def _load_directory(self, config_dir: Path) -> dict[str, Any]
Parameters
Name Type Description
config_dir —
Returns
dict[str, Any]