configblock.configblock module

Class to collect configuration information

class configblock.configblock.ConfigBlock(default_subconfig_type: Optional[Callable[[], ConfigBlock]] = None)

Bases: MutableMapping

Basic unit of the configuration

Each provides access to a set of configuration options. Blocks can be arranged in a hierarchical manner, with each deeper layer configuring more specific and detailed information. This allows a deep and complex configuration to be constructed from relatively simple blocks.

Each block can have three different sorts of configuration item in it:

Options: Provide a single piece of configuration information. Options are declared by the add_option function. Both the set and default values for options can be functions which take a single argument (the config block on which they are declared). In the cases the evaluation of these options is deferred until they are accessed and the function is used to calculate the value at the time of access. This allows having options whose values depend on the values of other options in the hierarchy
Predefined subconfigurations: Nested subconfigurations which are always present (but not necessarily active) on this block. These are declared by the add_subconfig function. Usually these will only be active if an option on them is set.
Extra subconfigurations: Nested subconfigurations which can be provided on the fly through the text configuration. The types of these configurations can be set in two ways. Usually a ‘Type’ key in the config file which then maps to a subconfiguration type declared by the add_subconfig_type function. Alternatively, a default subconfig type can be defined on a block.

The process of setting up a block goes in two main parts. First the python code sets up the set of allowed options, predefined subconfigurations and extra subconfiguration types. Then the user provides specific values for the options, usually from an external configuration file.

To reduce boilerplate in the configuration files there are a few shortcuts for setting specifc options a block:

First, the key it has in its parent object can be used to initialise certain keys in the block (note this is only relevant for extra subconfigs). This is customised through the set_from_key function.
Alternatively, the full block can be set from a single value, usually a string but can be any value which is not a Mapping. This is customised through the set_from_single_value function.

activate()

Make this subconfig active

Also recurses up the chain and sets all of its parents to be active

property active: bool: Whether this subconfig is active

add_enum_option(key: str, enum_type: Type[Enum], default: Union[Callable[[ConfigBlock], Any], Any] = None, help: str = None, required: bool = None, detail: int = 0, set_from_key: bool = False, set_from_single_value: bool = False, global_default: str = None)

Add a new option to this block

Parameters

key (str) – The name of the option. This forms the key in the configuration file and also in this mapping. It must not match any other declared option or any block.
enum_type (Type[enum.Enum]) – The type of the enum to be set
default (Union[DeferredValue, Any], optional) – The default value for this option. This can be a callable object (function) which takes the config as an argument.
help (str, optional) – Docstring describing the option
required (bool, optional) – Whether or not this value must be set by the configuration. If left as None it will be set to True if the default value is None.
detail (int, optional) – How detailed this information is. This is used by helper classes which print information about the available options. They can choose only to show options up to a certain level of detail
set_from_key (bool, optional) – If this option is not specified it will be set from the key that refers to this object in its parent config.
set_from_single_value (bool, optional) – If this config is set from a single value rather than a dictionary then this option will be set from that value.
global_default (str) – If set, the default value will instead be set to be a GlobalOption

Raises

ValueError – The provided key is invalid
KeyError – The provided key is already defined in this block

add_global_option(key: Union[str, Path], default: Optional[Union[Callable[[ConfigBlock], Any], Any]] = None, type: Optional[Callable] = None, help: Optional[str] = None, required: Optional[bool] = None, choices: Optional[Iterable] = None, validator: Optional[Callable[[Any], bool]] = None)

Add a global option to this configuration

Parameters

key (str) – The name of the option. This forms the key in the configuration file and also in this mapping. If it matches an existing option then it will be merged with it
default (Union[DeferredValue, Any], optional) – The default value for this option. This can be a callable object (function) which takes the config as an argument.
type (Callable, optional) – Optional conversion function from the type provided by the configuration to the type to be used in the code. Remember that the type from the configuration may be inferred by the configuration file parser
help (str, optional) – Docstring describing the option
required (bool, optional) – Whether or not this value must be set by the configuration. If left as None it will be set to True if the default value is None.
choices (Iterable, optional) – List of allowed values to be set for this option
validator (OptionValidator, optional) – Optional function to be called when setting this option. Should return False if the set value is invalid. Also allowed to raise an exception in this case

add_option(key: str, default: Union[Callable[[ConfigBlock], Any], Any] = None, type: Callable = None, help: str = None, required: bool = None, choices: Iterable = None, validator: Callable[[Any], bool] = None, detail: int = 0, set_from_key: bool = False, set_from_single_value: bool = False, global_default: str = None)

Add a new option to this block

Parameters

key (str) – The name of the option. This forms the key in the configuration file and also in this mapping. It must not match any other declared option or any block.
default (Union[DeferredValue, Any], optional) – The default value for this option. This can be a callable object (function) which takes the config as an argument.
type (Callable, optional) – Optional conversion function from the type provided by the configuration to the type to be used in the code. Remember that the type from the configuration may be inferred by the configuration file parser
help (str, optional) – Docstring describing the option
required (bool, optional) – Whether or not this value must be set by the configuration. If left as None it will be set to True if the default value is None.
choices (Iterable, optional) – List of allowed values to be set for this option
validator (OptionValidator, optional) – Optional function to be called when setting this option. Should return False if the set value is invalid. Also allowed to raise an exception in this case
detail (int, optional) – How detailed this information is. This is used by helper classes which print information about the available options. They can choose only to show options up to a certain level of detail
set_from_key (bool, optional) – If this option is not specified it will be set from the key that refers to this object in its parent config.
set_from_single_value (bool, optional) – If this config is set from a single value rather than a dictionary then this option will be set from that value.
global_default (str) – If set, the default value will instead be set to be a GlobalOption

Raises

ValueError – The provided key is invalid
KeyError – The provided key is already defined in this block

add_subconfig(key: str, config: ConfigBlock, always: bool = False)

Add a new subconfig

Parameters

key (str, Path) – The name of the subconfiguration. This forms the key in the configuration file and also in this mapping. It must not match any other declared option or any block.
config (ConfigBlock) – The configuration block to add
always (bool) – Whether the block is always active. If False the block will only be active if one of its options is set

Raises

ValueError – The provided key is invalid
KeyError – The provided key is already defined in this block

add_subconfig_type(key: str, factory: Callable[[], ConfigBlock])

Add a new subconfiguration type that can be added as an extra subconfig

Parameters

key (str) – The name of the subconfig type, will be matched to the ‘Type’ field in the configuration file
factory (ConfigBlockFactory) – Function that produces a ConfigBlock from its parent and key in the parent. Can usually be a ConfigBlock class so long as its __init__ method has the correect signature

Raises

KeyError – The subconfig type name is already registered

clear()

Remove all configuration-specific information from this.

All options and configs remain declared, but with their values set back to defaults. This is the equivalent of calling del on all keys

property default_subconfig_type: Optional[Callable[[], ConfigBlock]]: The default subconfig type factory

property full_path: Path: The full path for this object

get_option_data(key: str) → OptionData

Get the data for the specified option

Raises: KeyError – The provided key is not an option

get_option_value(key: str)

Get the value for the specified option

If the value is not set, the default will be returned instead. If no defaullt is set then None will be returned

Raises: KeyError – The specified key is not an option or a required option is not set

get_subconfig(key: str) → ConfigBlock

Get a subconfig (predefined or extra)

Raises: KeyError – The specified key is not a subconfig

property globals: GlobalConfigBlock: The global configs

is_extra_subconfig(key: str) → bool: Returns whether or not the provided key is an extra subconfig

is_option(key: str) → bool: Test if the specified key is an option

is_option_set(key: str) → bool

Whether the specified option is set

Raises: KeyError – The provided key is not an option

is_predefined_subconfig(key: str) → bool: Returns whether or not the provided key is a predefined subconfig

property is_root: bool: Whether this is the root block

is_set_from_key(key: str) → bool: Whether the specified option is set from the key

is_set_from_single_value(key: str) → bool: Whether the specified option is set from a single value

is_subconfig(key: str) → bool: Returns whether or not the provided key is a subconfig

iter_option_data(nested: bool = False, only_active: bool = True, include_globals=True) → Iterable[Tuple[Path, OptionData]]

Iterate over the options on this block

Parameters

nested (bool) – If True, iterate through all nested subconfigs as well.
only_active (bool) – If True, only look at active nested subconfigs.
include_globals (bool) – If True, include the global options if nested is also True

iter_paths(nested: bool = False, only_active: bool = True, include_globals=True) → Iterable[Path]

Iterate over all paths

Parameters

nested (bool) – If True, iterate through all nested subconfigs as well.
only_active (bool) – If True, only look at active subconfigs.
include_globals (bool) – If True, include the globals

iter_predefined_subconfigs(nested: bool = False, only_active: bool = True) → Iterable[Tuple[Path, ConfigBlock]]

Iterate over the predefined subconfigs on this block

Parameters

nested (bool) – If True, iterate through all nested subconfigs as well. This only iterates through predefined subconfigs.
only_active (bool) – If True, only look at active subconfigs.

iter_subconfig_types() → Iterable[Tuple[str, Callable[[], ConfigBlock]]]: Iterate over the defined subconfig types

iter_subconfigs(nested: bool = False, only_active: bool = True) → Iterable[Tuple[Path, ConfigBlock]]

Iterate over the subconfigs on this block

Parameters

nested (bool) – If True, iterate through all nested subconfigs as well.
only_active (bool) – If True, only look at active subconfigs.

property key_in_parent: Optional[str]: The key this has in its parent

property n_extra_subconfig_types: int: The number of extra subconfig types defined on this

property n_extra_subconfigs: int: The number of extra subconfigs directly defined on this

property n_options: int: The number of options directly defined on this

property n_predefined_subconfigs: int: The number of predefined subconfigs directly defined on this

property n_subconfigs: int: The total number of subconfigs defined on this

property parent: ConfigBlock: The parent block for this block (None if this is the root object)

remove_extra_subconfig(key: str)

Completely remove the specified subconfig

Raises: KeyError – The specified key is not an extra subconfig

remove_option(key: str)

Remove a named option

Raises: KeyError – The provided key is not an option

remove_option_value(key: str)

Remove the set value for the specified option

Raises: KeyError – The specified key is not an option

remove_subconfig(name: str)

Remove a predefined subconfiguration

Raises: KeyError – The provided name is not a predefined subconfiguration

remove_subconfig_type(name: str)

Remove an already declared subconfig type

Raises: KeyError – The provided name is not a subconfiguration type

reset_predefined_subconfig(key: str)

Reset all options on the specified subconfig

Raises: KeyError – The specified key is not a predefined subconfig

property root: ConfigBlock: Return the root block of the hierarchy

set(value)

Set the values for this config

If the value is a mapping, this just calls the update function (set key, value pairs from the input mapping). Otherwise anything in the self._set_from_single_value list is set from that value.

set_from_key(key): Set information in this object from the key it has in its parent

set_from_single_value(value): Set the values for this config from a single (non-dictionary) value

set_option_value(key: str, value)

Set the value for the specified option

Can also raise any exception that the validator can raise

Raises: KeyError – The specified key is not an option

set_parent(parent: ConfigBlock, key: str)

Set the parent for this block

If this currently has a parent it will remove itself from it first

Parameters

parent (ConfigBlock) – The new parent block
key (str) – The key in the new parent block

set_subconfig(key: str, value: Any)

Set a subconfig

Raises

KeyError – The specified key already refers to an option or the specified type is unknown
ValueError – The key is not a predefined subconfiguration, the provided value does not contain a ‘Type’ key and no default subconfig type is set

to_dict(validate: bool = True) → Dict[str, Any]

Convert this to a basic python dictionary

Parameters: validate (bool) – If True, first validate the configuration, by default True

classmethod valid_key(key: str) → bool

Return whether or not this is a valid key

Parameters: key (str) – _description_

validate()

Check that the configuration is complete and correct

All subconfigurations will be checked and a ValueError raised if any are wrong

configblock.configblock.ConfigBlockFactory

Function type to create a new ConfigBlock

alias of Callable[[], ConfigBlock]

configblock.configblock.DeferredValue

Function type for set/default valules of options whose evaluation is deferred

alias of Callable[[ConfigBlock], Any]

class configblock.configblock.GlobalConfigBlock

Bases: ConfigBlock

Config block representing global values

Global values are special - they are typically used to set default values at several places in the configuration. They should not be directly declared, but rather declared as default values for options in the rest of the tree.

add_option(key: str, default: Optional[Union[Callable[[ConfigBlock], Any], Any]] = None, type: Optional[Callable] = None, help: Optional[str] = None, required: Optional[bool] = None, choices: Optional[Iterable] = None, validator: Optional[Callable[[Any], bool]] = None, set_from_key: bool = False, set_from_single_value: bool = False)

Add a new option to this block

Parameters

key (str) – The name of the option. This forms the key in the configuration file and also in this mapping. It must not match any other declared option or any block.
default (Union[DeferredValue, Any], optional) – The default value for this option. This can be a callable object (function) which takes the config as an argument.
type (Callable, optional) – Optional conversion function from the type provided by the configuration to the type to be used in the code. Remember that the type from the configuration may be inferred by the configuration file parser
help (str, optional) – Docstring describing the option
required (bool, optional) – Whether or not this value must be set by the configuration. If left as None it will be set to True if the default value is None.
choices (Iterable, optional) – List of allowed values to be set for this option
validator (OptionValidator, optional) – Optional function to be called when setting this option. Should return False if the set value is invalid. Also allowed to raise an exception in this case
detail (int, optional) – How detailed this information is. This is used by helper classes which print information about the available options. They can choose only to show options up to a certain level of detail
set_from_key (bool, optional) – If this option is not specified it will be set from the key that refers to this object in its parent config.
set_from_single_value (bool, optional) – If this config is set from a single value rather than a dictionary then this option will be set from that value.
global_default (str) – If set, the default value will instead be set to be a GlobalOption

Raises

ValueError – The provided key is invalid
KeyError – The provided key is already defined in this block

add_subconfig_type(key: str, factory: Callable[[], ConfigBlock])

Add a new subconfiguration type that can be added as an extra subconfig

Parameters

key (str) – The name of the subconfig type, will be matched to the ‘Type’ field in the configuration file
factory (ConfigBlockFactory) – Function that produces a ConfigBlock from its parent and key in the parent. Can usually be a ConfigBlock class so long as its __init__ method has the correect signature

Raises

KeyError – The subconfig type name is already registered

log = <Logger configblock.configblock.GlobalConfigBlock (WARNING)>

merge(other: GlobalConfigBlock): Merge this with another config block

class configblock.configblock.GlobalOption(path: Path, data: OptionData)

Bases: OptionReference

Helper class to set an option to default to a global option

Adding an option with this as a default will also add the relevant option into the configurations ‘/Globals’ section

class configblock.configblock.OptionData(default: Optional[Union[Callable[[ConfigBlock], Any], Any]] = None, type: Optional[Callable[[Any], Any]] = None, help: Optional[str] = None, required: bool = False, choices: Optional[Tuple[Any]] = None, validator: Optional[Callable[[Any], bool]] = None, detail: int = 0)

Bases: object

Contain all the information about a declared option (before its value is set)

choices: Tuple[Any] = None: A list of valid values for the option

default: Union[Any, Callable[[ConfigBlock], Any]] = None: The default value

detail: int = 0: How detailed this information is. Classes to print out the full configuration can use this to decided to skip options

help: str = None: Help string to document the purpose (and potentially a brief summary of the use) of an option

required: bool = False: Whether or not an option is required for the configuration to be valid

type: Callable[[Any], Any] = None: The type of the value - essentially used as a conversion function

validator: Callable[[Any], bool] = None: An optional function that should return False if the provided value is incorrect (also allowed to raise an exception)

class configblock.configblock.OptionReference(path: Path)

Bases: object

Helper class to set the value of an option to copy a different option in the hierarchy

property description: str

property path: Path: The path this refers to

configblock.configblock.OptionValidator

Function that throws an exception if the provided value is incorrect

alias of Callable[[Any], bool]

configblock.configblock.recurse(func)

Wrap a function that acts on a config block + key to act on any path in the hierarchy

The provided function must take a ConfigBlock as its first argument and a key within that block as its second. The produced wrapper function takes care of navigating through the hierarchy to the relevant point before calling the wrapped function.

TODO: example