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.
ConfigInt	Integer configuration node.
ConfigFloat	Float configuration node.
ConfigBool	Boolean configuration node.
ConfigStr	String configuration node.
ConfigPath	File pathname configuration node.
ConfigEnum	'Enum' configuration node.
ConfigLeafNode	Mixin class for configuration nodes.

class ConfigLeafNode(value=None, default=None, **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.

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 ConfigInt(value=0, default=None, min_value=None, max_value=None, wrapping=False)

Bases: ConfigLeafNode, int

Integer configuration node.

Parameters:

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

• default (int) – Default value of the node.

• min_value (int) – Minimum permissible value.

• max_value (int) – Maximum permissible value.

• wrapping (bool) – Should the value change to min_value when incremented beyond max_value or vice versa.

class ConfigBool(value=False, default=None, **kwds)

Bases: ConfigInt

Boolean configuration node.

Parameters:

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

• default (bool) – Default value of the node.

class ConfigFloat(value=0.0, default=None, min_value=None, max_value=None, decimals=8, wrapping=False)

Bases: ConfigLeafNode, float

Float configuration node.

Parameters:

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

• default (float) – Default value of the node.

• min_value (float) – Minimum permissible value.

• max_value (float) – Maximum permissible value.

• decimals (int) – How many decimal places to use when displaying the value.

• wrapping (bool) – Should the value change to min_value when incremented beyond max_value or vice versa.

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

Bases: ConfigLeafNode, str

String configuration node.

Parameters:

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

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

class ConfigPath(value='', default=None, exists=True)

Bases: ConfigStr

File pathname configuration node.

Parameters:

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

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

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

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

Bases: ConfigStr

‘Enum’ configuration node.

The value can be one of a list of choices.

Parameters:

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

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

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

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

class ConfigParent(config_map={})

Bases: object

Parent configuration node.

Stores a set of child nodes in a dict. In a Compound component the children are themselves ConfigParent nodes, allowing components to be nested to any depth whilst making their configuration accessible from the top level.

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

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 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.