nicetoolbox.configs.placeholders

Functions

get_placeholders	Extract all placeholder names from any data structure.
get_placeholders_str	Extract all placeholder names from a string.
resolve_placeholders	Recursively find and resolve placeholders in input data with corresponding values.
resolve_placeholders_dict_mut	Resolve placeholders in a dict using both provided context and self-references.
resolve_placeholders_str	Find and resolve placeholders in a string with corresponding values from dictionary.
resolve_placeholders_str_strict	Same as resolve_placeholders_str, but raise if finds unexpected placeholders.

nicetoolbox.configs.placeholders.get_placeholders(input: Any) → set[str]

Extract all placeholder names from any data structure.

nicetoolbox.configs.placeholders.get_placeholders_str(input: str) → set[str]

Extract all placeholder names from a string.

nicetoolbox.configs.placeholders.resolve_placeholders(input: Any, placeholders: dict[str, Union[str, int, float, bool]], unreachable: set[str] | None = None) → Any

Recursively find and resolve placeholders in input data with corresponding values. Placeholders should be formatted as <var> strings inside data structure fields. If placeholders key isn’t inside dict or can’t be resolved from local context, it will rise resolution error.

Parameters:

• input – The data structure to be processed. Only strings, lists, dicts and pydantics.BaseModel are processed. Other input is returned as is.

• placeholders (dict[str, PLACEHOLDERS_TYPE]) – A dictionary containing the placeholder values.

• unreachable (set, optional) – Set of placeholder names that are allowed to remain unresolved (e.g., runtime placeholders resolved later).

Returns:

The copy of processed data structure with placeholders replaced.

Raises:

• ValueError – If dict-level placeholders cannot be resolved (circular dependencies or missing placeholders that are not in unreachable set).

• KeyError – If there’s a field name collision between input dict and placeholders dict when processing inputs.

nicetoolbox.configs.placeholders.resolve_placeholders_dict_mut(input: dict[str, Union[str, int, float, bool]], placeholders: dict[str, Union[str, int, float, bool]], unreachable: set[str] | None = None, max_iterations: int = 5) → dict[str, Any]

Resolve placeholders in a dict using both provided context and self-references. Iteratively resolves <var> placeholders in string values using: 1. Provided placeholders dict 2. Other string values within the same dict (self-reference)

Input placeholders dictionary will be mutated with new local placeholders.

Resolution continues until no changes occur or max_iterations is reached. Non-string values (numbers, lists, nested dicts) are returned unchanged. Function expects to resolve all known placeholders or raise an error.

Parameters:

• input (dict[str, PLACEHOLDERS_TYPE]) – Dict containing string values to resolve.

• placeholders (dict[str, Any]) – Context dict for resolution. Will be mutated to include resolved string values from input.

• unreachable (Optional[set[str]]) – Placeholder names that are allowed to remain unresolved (e.g., runtime placeholders resolved later).

• max_iterations (int) – Maximum resolution passes to handle chained dependencies.

Returns:

Dict with all resolvable placeholders replaced.

Raises:

• ValueError – If unresolved placeholders remain that are not in unreachable (indicates typos or circular dependencies).

• KeyError – If placeholders and input dicts have names collision (including non-string fields names)

nicetoolbox.configs.placeholders.resolve_placeholders_str(input: str, placeholders: dict[str, Union[str, int, float, bool]], unresolved: set[str] | None = None, unreachable: set[str] | None = None) → str

Find and resolve placeholders in a string with corresponding values from dictionary. Placeholders should be formatted as <var> strings. If placeholders key isn’t inside dict, it will be ignored and added to optional unresolved placeholders set.

Parameters:

• input (str) – The string containing placeholders to be replaced.

• placeholders (dict[str, PLACEHOLDERS_TYPE]) – A dictionary containing the placeholder values.

• unresolved (set, optional) – A set to collect unresolved placeholder keys. Placeholder is unresolved if it’s not present in dict or its value contains unresolved placeholders (including unreachable placeholders).

• unreachable (set, optional) – Set of placeholder names that are allowed to remain unresolved (e.g., runtime placeholders resolved later).

Returns:

The string with placeholders replaced.

Return type:

str

nicetoolbox.configs.placeholders.resolve_placeholders_str_strict(input: str, placeholders: dict[str, Union[str, int, float, bool]], unreachable: set[str] | None = None) → str

Same as resolve_placeholders_str, but raise if finds unexpected placeholders.