core.config

Component configuration classes.

The ConfigMixin mixin class is used with every component to provide a hierarchical tree of named configuration values. Each configuration value node has a fixed type and can be configured to have constraints such as maximum and minimum values.

Configuration values are accessed in a dictionary-like manner. During a component’s initialisation you should create the required configuration nodes like this:

self.config['zlen'] = ConfigInt(value=100, min_value=1)
self.config['looping'] = ConfigEnum(choices=('off', 'repeat'))

Subsequently the config object behaves more like a dictionary:

self.config['zlen'] = 250
...
zlen = self.config['zlen']

Users of a component can initialise its configuration by passing a config dict or key-value pairs to the component’s constructor:

resize = Resize(config={'xup': xup}, xdown=xdown)

The configuration can be changed, even when the component is running, with the get_config and set_config methods:

cfg = resize.get_config()
cfg['xup'] = 3
cfg['xdown'] = 4
resize.set_config(cfg)

Or, more simply:

resize.set_config(xup=3, xdown=4)

Note that these methods are thread-safe and make a copy of the configuration tree. This ensures that all your configuration changes are applied together, some time after calling set_config.

ConfigMixin	Add a config tree to a pyctools component.
ConfigParent	Parent configuration node.
CompoundConfig	Configuration node for Compound components.
ConfigLeafNode	Mixin class for configuration nodes.
BoundedConfigLeafNode	Numerical configuration node with min and/or max bounds.
ConfigInt	Integer configuration node.
ConfigFloat	Float configuration node.
ConfigBool	Boolean configuration node.
ConfigStr	String configuration node.
ConfigPath	File pathname configuration node.
ChoicesConfigLeafNode	Configuration node with a list of choices.
ConfigEnum	String 'enum' configuration node.
ConfigIntEnum	Integer 'enum' configuration node.

class ConfigLeafNode(value, **kwds)

Bases: object

Mixin class for configuration nodes.

This can be used with immutable Python types such as int or str to define a class that stores data of the Python type but has some extra attributes and methods.

Parameters:

• value – Initial (default) value of the node.

• kwds – Any other node attributes.

has_default = True

The node has a meaningful default value.

enabled = True

The node is currently enabled.

parser_add(parser, key)

Add information to a argparse CLI parser.

update(value)

Adjust the config item’s value.

copy()

Copy the config item’s value.

class BoundedConfigLeafNode(value, min_value=None, max_value=None, **kwds)

Bases: ConfigLeafNode

Numerical configuration node with min and/or max bounds.

Parameters:

• value (int or float) – Initial (default) value of the node.

• min_value (int or float) – Minimum permissible value.

• max_value (int or float) – Maximum permissible value.

class ConfigInt(value=0, **kwds)

Bases: BoundedConfigLeafNode, int

Integer configuration node.

Parameters:

value (int) – Initial (default) value of the node.

class ConfigBool(value=False, **kwds)

Bases: ConfigLeafNode, int

Boolean configuration node.

Parameters:

value (object or on or off) – Initial (default) value of the node.

class ConfigFloat(value=0.0, **kwds)

Bases: BoundedConfigLeafNode, float

Float configuration node.

Parameters:

value (float) – Initial (default) value of the node.

decimals = 8

How many decimal places to use when displaying the value.

class ConfigStr(value='', **kwds)

Bases: ConfigLeafNode, str

String configuration node.

Parameters:

value (str) – Initial (default) value of the node.

class ConfigPath(value='', exists=True, **kwds)

Bases: ConfigStr

File pathname configuration node.

Parameters:

• value (str) – Initial (default) value of the node.

• exists (bool) – If True, value must be an existing file.

class ChoicesConfigLeafNode(value=None, choices=[], extendable=False, **kwds)

Bases: ConfigLeafNode

Configuration node with a list of choices.

Parameters:

• value (int or str or None) – Initial (default) value of the node.

• choices (list) – a list of possible values of the config item. If value is None the first in the list is used.

• extendable (bool) – The choices list be extended by setting new values.

class ConfigEnum(value=None, choices=[], extendable=False, **kwds)

Bases: ChoicesConfigLeafNode, str

String ‘enum’ configuration node.

class ConfigIntEnum(value=None, choices=[], extendable=False, **kwds)

Bases: ChoicesConfigLeafNode, int

Integer ‘enum’ configuration node.

class ConfigParent

Bases: object

Parent configuration node.

Stores a set of child nodes in a dict.

audit_string()

Generate a string suitable for use in an audit trail.

Converts a component’s configuration settings to a Metadata audit trail string. This is a convenient way to add to the audit trail in a “standard” format. Only the non-default settings are shown, to keep the audit trail short but useful.

parser_add(parser, prefix='')

Add config to an argparse.ArgumentParser object.

The parser’s add_argument method is called for each config item. The argument name is constructed from the parent and item names, with a dot separator.

Parameters:

• parser (argparse.ArgumentParser) – The argument parser object.

• prefix (str) – The parent node name.

parser_set(args)

Set config from an argparse.Namespace object.

Call this method with the return value from parse_args.

Parameters:

args (argparse.Namespace) – The populated argparse.Namespace object.

class CompoundConfig(config_map={})

Bases: ConfigParent

Configuration node for Compound components.

Stores a set of ConfigParent nodes in a dict. This allows components to be nested to any depth whilst making their configuration accessible from the top level.

The config_map is used to allow multiple child components to be controlled by one config value.

class ConfigMixin(**kwds)

Bases: object

Add a config tree to a pyctools component.

get_config()

Get a copy of the component’s current configuration.

Using a copy allows the config to be updated in a threadsafe manner while the component is running. Use the set_config method to update the component’s configuration after making changes to the copy.

Returns:

Copy of component’s configuration.

Return type:

ConfigParent

set_config(config={}, **kwds)

Update the component’s configuration.

Use the get_config method to get a copy of the component’s configuration, update that copy then call set_config to update the component. This enables the configuration to be changed in a threadsafe manner while the component is running, and allows several values to be changed at once.

Parameters:

config (ConfigParent) – New configuration.

update_config()

Pull any changes made with set_config.

Call this from within your component before using any config values to ensure you have the latest values set by the user.

---

Comments or questions? Please email jim@jim-easterbrook.me.uk.