The Config Tree
A configuration structure which supports cascading layers.
In vivarium
it allows base configurations to be overridden by component
level configurations which are in turn overridden by model level configuration
which can be overridden by user supplied overrides. From the perspective
of normal client code the cascading is hidden and configuration values
are presented as attributes of the configuration object the values of
which are the value of that key in the outermost layer of configuration
where it appears.
For example:
>>> config = ConfigTree(layers=['inner_layer', 'middle_layer', 'outer_layer', 'user_overrides'])
>>> config.update({'section_a': {'item1': 'value1', 'item2': 'value2'}, 'section_b': {'item1': 'value3'}}, layer='inner_layer')
>>> config.update({'section_a': {'item1': 'value4'}, 'section_b': {'item1': 'value5'}}, layer='middle_layer')
>>> config.update({'section_b': {'item1': 'value6'}}, layer='outer_layer')
>>> config.section_a.item1
'value4'
>>> config.section_a.item2
'value2'
>>> config.section_b.item1
'value6'
- exception vivarium.config_tree.ConfigurationError(message, value_name)[source]
Base class for configuration errors.
- exception vivarium.config_tree.ConfigurationKeyError(message, value_name)[source]
Error raised when a configuration lookup fails.
- exception vivarium.config_tree.DuplicatedConfigurationError(message, name, layer, source, value)[source]
Error raised when a configuration value is set more than once.
- layer
The configuration layer at which the value is being set.
- source
The original source of the configuration value.
- value
The original configuration value.
- class vivarium.config_tree.ConfigNode(layers, name)[source]
A priority based configuration value.
A
ConfigNode
represents a single configuration value with priority-based layers. The intent is to allow a value to be set from sources with different priorities and to record what the value was set to and from where.For example, a simulation may need certain values to always exist, and so it will set them up at a “base” layer. Components in the simulation may have a different set of priorities and so override the “base” value at a “component” level. Finally a user may want to override the simulation and component defaults with values at the command line or interactively, and so those values will be set in a final “user” layer.
A
ConfigNode
may only have a value set at each layer once. Attempts to set a value at the same layer multiple times will result in aDuplicatedConfigurationError
.The
ConfigNode
will record all values set and the source they are set from. This sort of provenance with configuration data greatly eases debugging and analysis of simulation code.This class should not be instantiated directly. All interaction should take place by manipulating a
ConfigTree
object.- freeze()[source]
Causes the
ConfigNode
node to become read only.This can be used to create a contract around when the configuration is modifiable.
- get_value(layer=None)[source]
Returns the value at the specified layer.
If no layer is specified, the outermost (highest priority) layer at which a value has been set will be used.
- update(value, layer, source)[source]
Set a value for a layer with optional metadata about source.
- Parameters:
- Raises:
ConfigurationError – If the node is frozen.
ConfigurationKeyError – If the provided layer does not exist.
DuplicatedConfigurationError – If a value has already been set at the provided layer or a value is already in the outermost layer and no layer has been provided.
- class vivarium.config_tree.ConfigTree(data=None, layers=None, name='')[source]
A container for configuration information.
Each configuration value is exposed as an attribute the value of which is determined by the outermost layer which has the key defined.
- freeze()[source]
Causes the ConfigTree to become read only.
This is useful for loading and then freezing configurations that should not be modified at runtime.
- items()[source]
Return an iterable of all (child_name, child) pairs.
- Return type:
Iterable[Tuple[str, ConfigTree | ConfigNode]]
- to_dict()[source]
Converts the ConfigTree into a nested dictionary.
All metadata is lost in this conversion.
- Return type:
- get_from_layer(name, layer=None)[source]
Get a configuration value from the provided layer.
If no layer is specified, the outermost (highest priority) layer at which a value has been set will be used.
- update(data, layer=None, source=None)[source]
Adds additional data into the
ConfigTree
.- Parameters:
data (Dict | str | Path | ConfigTree | None) –
update()
accepts many types of data.dict
: Flat or nested dictionaries may be provided. Keys of dictionaries at all levels must be strings.ConfigTree
: AnotherConfigTree
can be used. All source information will be ignored and the provided layer and source will be used to set the metadata.str
: Strings provided can be yaml formatted strings, which will be parsed into a dictionary using standard yaml parsing. Alternatively, a path to a yaml file may be provided and the file will be read in and parsed.pathlib.Path
: A path object to a yaml file will be interpreted the same as a string representation.
layer (str) – The name of the layer to store the value in. If no layer is provided, the value will be set in the outermost (highest priority) layer.
source (str) – The source to attribute the value to.
- Raises:
ConfigurationError – If the
ConfigTree
is frozen or attempting to assign an invalid value.ConfigurationKeyError – If the provided layer does not exist.
DuplicatedConfigurationError – If a value has already been set at the provided layer or a value is already in the outermost layer and no layer has been provided.