configblock.utils module

Helper functions for working with ConfigBlocks

configblock.utils.find_blocks(cfg: ConfigBlock, condition: Callable[[ConfigBlock], bool], max_steps: int = -1, only_active: bool = True) → Tuple[ConfigBlock, ...]

Find the closest config blocks in the overall hierarchy that satisfy a condition

First the children of the provided block are searched. Then if none are found the process is repeated on the parent block. This is continued until the root of the hierarchy is reached or the max_steps up have been performed.

Parameters:

  • cfg (ConfigBlock) – The starting block

  • condition (Callable[[ConfigBlock], bool]) – The condition to require on the returned configuration blocks

  • max_steps (int, optional) – The number of steps up to allow. A value of 0 means that only the children of cfg are searched. A negative value guarantees searching the entire hierarchy. Defaults to -1

  • only_active (bool, optional) – Only consider active blocks.

Returns:

The first encountered non-empty tuple of matching blocks. Empty if no matching blocks are found.

Return type:

Tuple[ConfigBlock, …]

configblock.utils.find_option_on_block_of_type(type: Type[ConfigBlock], key: str, default=None, required: bool | None = None, max_steps: int = -1, only_active: bool = True, docstring: str | None = None)

Create a function that searches for a value on another config block of the specified type in the hierarchy

Parameters:

  • type (Type[ConfigBlock]) – The type of block to search for

  • key (str) – The option to read

  • default (_type_, optional) – Default value if no matching block is found, by default None

  • required (bool, optional) – Whether to raise an exception if no default is found. If left as None it will be set to True if the default value is None.

  • max_steps (int, optional) – The number of steps up to allow. A value of 0 means that only the children of cfg are searched. A negative value guarantees searching the entire hierarchy. Defaults to -1

  • only_active (bool, optional) – Only consider active blocks.

  • docstring (str, optional) – Docstring of the created function

configblock.utils.find_option_on_matching_block(subcfg_condition: Callable[[ConfigBlock], bool], key: str, default=None, required: bool | None = None, max_steps: int = -1, only_active: bool = True, docstring: str | None = None)

Create a function that searches for a value on another block in the hierarchy

Parameters:

  • subcfg_condition (Callable[[ConfigBlock], bool]) – Condition which the other block must satisfy

  • key (str) – The option to read

  • default (_type_, optional) – Default value if no matching block is found, by default None

  • required (bool, optional) – Whether to raise an exception if no default is found. If left as None it will be set to True if the default value is None.

  • max_steps (int, optional) – The number of steps up to allow. A value of 0 means that only the children of cfg are searched. A negative value guarantees searching the entire hierarchy. Defaults to -1

  • only_active (bool, optional) – Only consider active blocks.

  • docstring (str, optional) – Docstring of the created function

configblock.utils.mk_optional(func: Callable[[Any], Any])

Return a modified function that handles optional values correctly

When the first argument to the wrapped function is ‘None’ then the modified function returns None.

configblock.utils.wrap_deferred_func(func: Callable, doc: str | None = None, rename_: Dict[str, str] | None = None, setdefault_: Dict[str, Any] | None = None, make_optional: bool = False)

Wrap another function so it can be used as a deferred value for a config block

Deferred values take the config block as an argument which acts similarly to a python dictionary. However most ‘normal’ functions will just take a list of named arguments. This function provides a way to wrap a ‘normal’ function so that it reads the relevant arguments from the configuration block.

Parameters:

  • func (Callable) – The function to wrap

  • doc (str, optional) – A docstring for the function (used by help printers), otherwise use the wrapped function’s docstring.

  • rename (Dict[str, str], optional) – Mapping from the parameter name in the wrapped function to the name of the corresponding option. Any kwargs to be used must be given here

  • setdefault (Dict[str, Any], optional) – Set any extra parameters for the function from here

  • make_optional (bool) – If True, apply mk_optional to the function

Raises:

ValueError – The function contains a varargs argument: this is not supported