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
.
Add a config tree to a pyctools component. |
|
Parent configuration node. |
|
Integer configuration node. |
|
Float configuration node. |
|
Boolean configuration node. |
|
String configuration node. |
|
File pathname configuration node. |
|
'Enum' configuration node. |
|
Mixin class for configuration nodes. |
- class ConfigLeafNode(value=None, default=None, **kwds)[source]
Bases:
object
Mixin class for configuration nodes.
This can be used with immutable Python types such as
int
orstr
to define a class that stores data of the Python type but has some extra attributes and methods.
- class ConfigInt(value=0, default=None, min_value=None, max_value=None, wrapping=False)[source]
Bases:
ConfigLeafNode
,int
Integer configuration node.
- class ConfigBool(value=False, default=None, **kwds)[source]
Bases:
ConfigInt
Boolean configuration node.
- class ConfigFloat(value=0.0, default=None, min_value=None, max_value=None, decimals=8, wrapping=False)[source]
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)[source]
Bases:
ConfigLeafNode
,str
String configuration node.
- class ConfigPath(value='', default=None, exists=True)[source]
Bases:
ConfigStr
File pathname configuration node.
- class ConfigEnum(value=None, default=None, choices=[], extendable=False)[source]
Bases:
ConfigStr
‘Enum’ configuration node.
The value can be one of a list of choices.
- Parameters:
- class ConfigParent(config_map={})[source]
Bases:
object
Parent configuration node.
Stores a set of child nodes in a
dict
. In aCompound
component the children are themselvesConfigParent
nodes, allowing components to be nested to any depth whilst making their configuration accessible from the top level.The
config_map
is used inCompound
components to allow multiple child components to be controlled by one config value.- audit_string()[source]
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='')[source]
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)[source]
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)[source]
Bases:
object
Add a config tree to a pyctools component.
- get_config()[source]
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:
- set_config(config={}, **kwds)[source]
Update the component’s configuration.
Use the
get_config
method to get a copy of the component’s configuration, update that copy then callset_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()[source]
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.