nicetoolbox.configs.config_loader

Classes

ConfigLoader

Configuration loader with placeholder resolution and validation.
class nicetoolbox.configs.config_loader.ConfigLoader(auto: dict[str, Union[str, int, float, bool]], runtime: set[str])[source]

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]

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

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[source]

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[source]

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.