nicetoolbox.configs.config_loader.ConfigLoader

class nicetoolbox.configs.config_loader.ConfigLoader(auto: dict[str, Union[str, int, float, bool]], runtime: set[str])

Bases: object

Configuration loader with placeholder resolution and validation.

auto_placeholders

Placeholders initialized from functions, available to all configurations.

Type:

dict[str, PLACEHOLDERS_TYPE]

runtime_placeholders

Placeholder names that should remain unresolved until runtime (e.g., video_length, session_id).

Type:

set[str]

global_placeholders

Placeholders made available to all subsequent config loads, built up by adding contexts from loaded configs.

Type:

dict[str, PLACEHOLDERS_TYPE]

Methods

extend_global_ctx	Extends the global placeholder context that will be available to all future load_config() calls.
load_config	Loads a TOML configuration file, resolves all placeholders using available contexts (auto, global and runtime) and validates the result against a Pydantic schema.
resolve	Recursively processes the configuration to replace all placeholder strings (formatted as <key>) with their corresponding values from the combined context (auto, global and runtime).

Attributes

auto_placeholders
runtime_placeholders
global_placeholders

extend_global_ctx(add_ctx: dict[str, Union[str, int, float, bool]] | BaseModel) → None

Extends the global placeholder context that will be available to all future load_config() calls. Typically used to register values from already-loaded configs (e.g., paths from machine_specific config).

Parameters:

• add_ctx (dict[str, PLACEHOLDERS_TYPE]) – Dictionary of placeholder key-value

• context. (pairs to add to the global) –

Raises:

KeyError – If any keys in add_ctx already exist in global_placeholders.

load_config(path: str, schema: type[ModelT], ignore_auto_and_global=False) → ModelT

Loads a TOML configuration file, resolves all placeholders using available contexts (auto, global and runtime) and validates the result against a Pydantic schema. The configuration is returned as a validated Pydantic model instance.

Parameters:

• path (str) – Path to the configuration file.

• schema (type[ModelT]) – Pydantic model class to validate the configuration.

• ignore_auto_and_global (bool, optional) – If True, excludes global and auto placeholders from resolution context. Used for self-contained configs like experiment that bundle their own dependencies. Defaults to False.

Returns:

Validated Pydantic model instance populated with resolved

config data.

Return type:

ModelT

Raises:

• FileNotFoundError – If the configuration file does not exist.

• NotImplementedError – If the file type is not .toml

• toml.TomlDecodeError – If the TOML file has syntax errors.

• ValueError – If placeholders cannot be resolved due to missing values, circular dependencies, or exceed max iterations.

• KeyError – If there’s a collision between placeholder contexts or between local config fields and placeholder names.

• ConfigValidationError – If the resolved configuration fails schema validation).

resolve(config: Any, runtime_ctx: dict[str, Union[str, int, float, bool]] | None = None, ignore_auto_and_global: bool = False) → Any

Recursively processes the configuration to replace all placeholder strings (formatted as <key>) with their corresponding values from the combined context (auto, global and runtime).

Parameters:

• config – Configuration data to resolve. Can be dict, list, Pydantic model, string or any nested combination.

• runtime_ctx (Optional[dict[str, PLACEHOLDERS_TYPE]], optional) – Additional placeholders to provide at runtime (e.g., current video name, session ID, active detector).

• ignore_auto_and_global (bool, optional) – If True, excludes global and auto placeholders from resolution context. Used for self-contained configs like experiment that bundle their own dependencies. Defaults to False.

Returns:

Copy of config with all resolvable placeholders replaced.

Type matches input type.

Raises:

• ValueError – If placeholders cannot be resolved due to missing values, circular dependencies, or max iterations exceeded.

• KeyError – If there’s a collision between placeholder contexts (auto, global, runtime) or between local config fields and placeholder names.