Module

config.directory_loader

Directory-based configuration loader.

Loads config from directory structure:

config/
├── _default/       # Base config
├── environments/   # Environment overrides
└── profiles/       # Profile settings

Merge order: defaults → environment → profile

View source
2 Classes

Classes

ConfigLoadError
Raised when config loading fails.
0

Raised when config loading fails.

Inherits from Exception
ConfigDirectoryLoader
Load configuration from directory structure. Supports: - Multi-file configs in _default/ - Environ…
10

Load configuration from directory structure.

Supports:

  • Multi-file configs in _default/
  • Environment-specific overrides
  • Profile-specific settings
  • Origin tracking for introspection

Methods 4

load
Load config from directory with precedence. Precedence (lowest to highest): 1.…
3 dict[str, Any] 
def load(self, config_dir: Path, environment: str | None = None, profile: str | None = None) -> dict[str, Any]

Load config from directory with precedence.

Precedence (lowest to highest):

  1. config/_default/*.yaml (base)
  2. config/environments/<env>.yaml (environment overrides)
  3. config/profiles/<profile>.yaml (profile settings)
Parameters 3
config_dir Path

Path to config directory
environment str | None

Environment name (auto-detected if None)
profile str | None

Profile name (optional)
Returns

dict[str, Any] —

Merged configuration dictionary

get_deprecated_keys
Get list of deprecated keys found (old_key, new_location, note).
0 list[tuple[str, str… 
def get_deprecated_keys(self) -> list[tuple[str, str, str]]

Get list of deprecated keys found (old_key, new_location, note).

Returns

list[tuple[str, str, str]]

print_deprecation_warnings
Print deprecation warnings if any deprecated keys were found.
0 None 
def print_deprecation_warnings(self) -> None

Print deprecation warnings if any deprecated keys were found.

get_origin_tracker
Get origin tracker if tracking is enabled.
0 ConfigWithOrigin | None 
def get_origin_tracker(self) -> ConfigWithOrigin | None

Get origin tracker if tracking is enabled.

Returns

ConfigWithOrigin | None —

Origin tracker, or None if tracking disabled

Internal Methods 6
__init__
Initialize loader.
1 None 
def __init__(self, track_origins: bool = False) -> None

Initialize loader.

Parameters 1
track_origins bool

Whether to track config origins for introspection
_load_directory
Load all YAML files in directory and merge.
2 dict[str, Any] 
def _load_directory(self, directory: Path, origin_prefix: str = '') -> dict[str, Any]

Load all YAML files in directory and merge.

Parameters 2
directory Path

Directory to load from
origin_prefix str

Prefix for origin tracking
Returns

dict[str, Any] —

Merged configuration from all files

_load_environment
Load environment-specific config.
2 dict[str, Any] | None 
def _load_environment(self, config_dir: Path, environment: str) -> dict[str, Any] | None

Load environment-specific config.

Parameters 2
config_dir Path

Root config directory
environment str

Environment name
Returns

dict[str, Any] | None —

Environment config, or None if not found

_load_profile
Load profile-specific config.
2 dict[str, Any] | None 
def _load_profile(self, config_dir: Path, profile: str) -> dict[str, Any] | None

Load profile-specific config.

Parameters 2
config_dir Path

Root config directory
profile str

Profile name
Returns

dict[str, Any] | None —

Profile config, or None if not found

_load_yaml
Load single YAML file with error handling.
1 dict[str, Any] 
def _load_yaml(self, path: Path) -> dict[str, Any]

Load single YAML file with error handling.

Parameters 1
path Path

Path to YAML file
Returns

dict[str, Any] —

Parsed YAML as dict

_flatten_config
Flatten nested config for backward compatibility with old ConfigLoader. Extrac…
1 dict[str, Any] 
def _flatten_config(self, config: dict[str, Any]) -> dict[str, Any]

Flatten nested config for backward compatibility with old ConfigLoader.

Extracts common sections to top level:

  • site.title → title
  • build.parallel → parallel
Parameters 1
config dict[str, Any]

Nested configuration dictionary
Returns

dict[str, Any] —

Flattened configuration (sections preserved, values also at top level)