zim.config.dicts.ConfigDict

class documentation

class ConfigDict(ControlledDict): (source)

The class defines a dictionary of config keys.

To add a key in this dictionary it must first be defined using one of the sub-classes of ConfigDefinition. This definition takes care of validating the value of the config keys and (de-)serializing the values from and to text representation used in the config files.

Both getting and setting a value will raise a KeyError when the key has not been defined first. An ValueError is raised when the value does not conform to the definition.

THis class derives from ControlledDict which in turn derives from DefinitionOrderedDict so changes to the config can be tracked by the changed signal, and values are kept in the same order so the order in which items are written to the config file is predictable.

Method	`__delitem__`	Undocumented
Method	`__init__`	Undocumented
Method	`__setitem__`	Undocumented
Method	`all_items`	Undocumented
Method	`copy`	Shallow copy of the items @returns: a new object of the same class with the same items
Method	`define`	Set one or more definitions for this config dict Can cause error log when values prior given to `input()` do not match the definition.
Method	`dump`	No summary
Method	`input`	No summary
Method	`setdefault`	Set the default value for a configuration item.
Method	`update`	No summary
Instance Variable	`definitions`	Undocumented
Method	`_set_input`	Undocumented
Instance Variable	`_input`	Undocumented

Inherited from ControlledDict:

Method	`changed`	Undocumented
Method	`do_changed`	Undocumented
Method	`on_child_changed`	Undocumented
Method	`set_modified`	Set the modified state. Used to reset modified to `False` after the configuration has been saved to file. @param modified: `True` or `False`
Class Variable	`__signals__`	Undocumented
Property	`modified`	`True` when the values were modified, used to e.g. track when a config needs to be written back to file
Instance Variable	`_modified`	Undocumented

Inherited from SignalEmitter (via ControlledDict):

Method	`__new__`	Undocumented
Method	`block_signals`	Returns a context manager for blocking one or more signals
Method	`connect`	Register a handler for a specific object.
Method	`connect_after`	Like `connect()` but handler will be called after default handler
Method	`disconnect`	Undocumented
Method	`emit`	Undocumented
Method	`emit_return_first`	Emits a signal and stops emission on the first handler that returns a not-None value.
Method	`emit_return_iter`	Returns an generator that calls one handler on each iteration and yields the return values. This allows aggregating return values.
Method	`_connect`	Undocumented
Method	`_setup_signal`	Undocumented
Method	`_teardown_signal`	Undocumented

Inherited from ConnectorMixin (via ControlledDict):

Method	`connectto`	Connect to signals of another object E.g.:
Method	`connectto_all`	Convenience method to combine multiple calls to `connectto()`.
Method	`disconnect_all`	Disconnect all signals that have been connected with `connectto` and friends. Typically called when you want to destroy this object.
Method	`disconnect_from`	Disc all signals that have been connected with `connectto` and friends to a specific object.
Method	`_disconnect_from`	Undocumented
Instance Variable	`_connected_signals`	Undocumented

def __delitem__(self, k): (source)

overrides zim.config.dicts.ControlledDict.__delitem__

Undocumented

def __init__(self, E=None, **F): (source)

overrides zim.config.dicts.ControlledDict.__init__

Undocumented

def __setitem__(self, k, v): (source)

overrides zim.config.dicts.ControlledDict.__setitem__

Undocumented

def all_items(self): (source)

Undocumented

def copy(self): (source)

Shallow copy of the items

Returns
a new object of the same class with the same items

def define(self, E=None, **F): (source)

Set one or more definitions for this config dict Can cause error log when values prior given to input() do not match the definition.

def dump(self): (source)

Returns a dict that combines the defined keys with any undefined input keys. Used e.g. when you only define part of the keys in the dict, but want to preserve all of them when writing back to a file.

def input(self, E=None, **F): (source)

Like update() but won't raise on failures. Values for undefined keys are stored and validated once the key is defined. Invalid values only cause a logged error message but do not cause errors to be raised.

def setdefault(self, key, default, check=None, allow_empty=False): (source)

Set the default value for a configuration item.

Parameters
key	the dict key
default	the default value for this key
check	the check to do on the values, when the check fails the value is considered mal-formed and the default is used while a warning is logged. If `check` is `None` the default behavior will be to compare the classes of the set value and the default and enforce them to be of the same type. Automatic conversion is done for values of type `list` with defaults of type `tuple`. And for defaults of type `str` or `unicode` the `basestring` type is used as check. As a special case when the default is `None` the check is not allowed to be `None` as well. If `check` is given and it is a class the existing value will be checked to be of that class. Same special case for tuples and strings applies here. If `check` is given and is a `set`, `list` or `tuple` the value will be tested to be in this set or list. If the default is an integer and `check` is a tuple of two integers, the check will be that the value is in this range. (For compatibility with `InputForm` extra argument for integer spin boxes.) If `check` is given and it is a function it will be used to check the value in the dictionary if it exists. The function is called as: check(value, default) Where `value` is the current value in the dict and `default` is the default value that was provided. The function can not only check the value, it can also do on the fly modifications, e.g. to coerce it into a specific type. If the value is OK the function should return the (modified) value, if not it should raise an `AssertionError`. When this error is raised the default is used and the dict is considered being modified. ( Note that 'assert' statements in the code can be removed by code optimization, so explicitly call "`raise AssertionError`". ) Examples of functions that can be used as a check are: `check_class_allow_empty` and `value_is_coord`.
allow_empty	if `True` the value is allowed to be empty (either empty string or `None`). In this case the default is not set to overwrite an empty value, but only for a mal-formed value or for a value that doesn't exist yet in the dict.
Note
Usage of this method with keyword arguments is depreciated, use `define()` instead. Compatible with `dict.setdefault()` but extended with functionality to check the value that is in the dict, and use the default if the value is mal-formed. This is used extensively in zim to do a sanity check on values in the configuration files. If you initialize the config items with this method you can assume them to be safe afterward and avoid a lot of checks or bugs later in the code.

def update(self, E=None, **F): (source)

overrides zim.config.dicts.ControlledDict.update

Like dict.update(), copying values from E or F. However if E is also a ConfigDict, also the definitions are copied along. Do use update() when setting multiple values at once since it results in emitting changed only once.

definitions = (source)

Undocumented

def _set_input(self, key, value): (source)

Undocumented

_input: dict = (source)

Undocumented