lib.config

This library does the handling and parsing of the configuration of SmartHomeNG.

Warning:

This library is part of the core of SmartHomeNG. It should not be called directly from plugins!

lib.config.add_struct_to_item_template(path, struct_name, template, struct_dict, instance)

Add the referenced struct to the items_template subtree

Parameter:

• path – Path of the item which references a struct (template)

• struct_name – Name of the to use for the item

• template – Template dict to be merged into the item tree

• struct_dict – dict with all defined structs (from /etc/structs.yaml and from loaded plugins)

• instance – For multi instance plugins: instance for which the items work (is derived from item with struct attribute)

Rückgabe:

lib.config.merge(source, destination, source_name='', dest_name='', filename='')

Merges an OrderedDict Tree into another one

Parameter:

• source (OrderedDict) – source tree to merge into another one

• destination (OrderedDict) – destination tree to merge into

Rückgabe:

Merged configuration tree

Rückgabetyp:

OrderedDict

Example:

Run me with nosetests –with-doctest file.py

>>> a = { 'first' : { 'all_rows' : { 'pass' : 'dog', 'number' : '1' } } }
>>> b = { 'first' : { 'all_rows' : { 'fail' : 'cat', 'number' : '5' } } }
>>> merge(b, a) == { 'first' : { 'all_rows' : { 'pass' : 'dog', 'fail' : 'cat', 'number' : '5' } } }
True

lib.config.merge_structlists(l1, l2, key='')

lib.config.nested_get(input_dict, path)

lib.config.nested_put(output_dict, path, value)

Parameter:

• output_dict – dict structure to write to

• path – path to write to

• value – value to write to the nested key

Rückgabe:

lib.config.parse(filename, config=None, addfilenames=False, parseitems=False, struct_dict={})

Load and parse a configuration file and merge it to the configuration tree Depending on the extension of the filename, the apropriate parser is called

Parameter:

• filename (str) – Name of the configuration file

• config (OrderedDict) – Optional OrderedDict tree, into which the configuration should be merged

• struct_dict – dict with all defined structs (from /etc/structs.yaml and from loaded plugins)

Rückgabe:

The resulting merged OrderedDict tree

Rückgabetyp:

OrderedDict

lib.config.parse_basename(basename, configtype='')

Load and parse a single configuration and merge it to the configuration tree The configuration is only specified by the basename. At the moment it looks for a .yaml file or a .conf file .yaml files take preference

Parameter:

• basename (str) – Name of the configuration

• configtype (str) – Optional string with config type (only used for log output)

Rückgabe:

The resulting merged OrderedDict tree

Rückgabetyp:

OrderedDict

lib.config.parse_conf(filename, config=None)

Load and parse a configuration file which is in the old .conf format of smarthome.py and merge it to the configuration tree

Parameter:

• filename (str) – Name of the configuration file

• config (bool) – Optional OrderedDict tree, into which the configuration should be merged

Rückgabe:

The resulting merged OrderedDict tree

Rückgabetyp:

OrderedDict

The config file should stick to the following setup:

[firstlevel]
    attribute1 = xyz
    attribute2 = foo
    attribute3 = bar

    [[secondlevel]]
        attribute1 = abc
        attribute2 = bar
        attribute3 = foo

        [[[thirdlevel]]]
            attribute1 = def
            attribute2 = barfoo
            attribute3 = foobar

    [[anothersecondlevel]]
        attribute1 = and so on

where firstlevel, secondlevel, thirdlevel and anothersecondlevel are defined as items and attribute are their respective attribute - value pairs

Valid characters for the items are a-z and A-Z plus any digit and underscore as second or further characters. Valid characters for the attributes are the same as for an item plus @ and *

lib.config.parse_itemsdir(itemsdir, item_conf, addfilenames=False, struct_dict={})

Load and parse item configurations and merge it to the configuration tree The configuration is only specified by the name of the directory. At the moment it looks for .yaml files and a .conf files Both filetypes are read, even if they have the same basename

Parameter:

• itemsdir (str) – Name of folder containing the configuration files

• item_conf (OrderedDict) – Optional OrderedDict tree, into which the configuration should be merged

• addfilenames –

• struct_dict (dict / OrderedDict) – dict with all defined structs (from /etc/structs.yaml and from loaded plugins)

Rückgabe:

The resulting merged OrderedDict tree

Rückgabetyp:

OrderedDict

lib.config.parse_yaml(filename, config=None, addfilenames=False, parseitems=False, struct_dict={})

Load and parse a yaml configuration file and merge it to the configuration tree

Parameter:

• filename (str) – Name of the configuration file

• config (bool) – Optional OrderedDict tree, into which the configuration should be merged

• addfilenames (bool) – x

• parseitems (bool) – x

• struct_dict (dict) – dictionary with stuct definitions (templates) for reading item tree

Rückgabe:

The resulting merged OrderedDict tree

Rückgabetyp:

OrderedDict

The config file should stick to the following setup:

firstlevel:
    attribute1: xyz
    attribute2: foo
    attribute3: bar

    secondlevel:
        attribute1: abc
        attribute2: bar
        attribute3: foo

        thirdlevel:
            attribute1: def
            attribute2: barfoo
            attribute3: foobar

    anothersecondlevel:
        attribute1: and so on

where firstlevel, secondlevel, thirdlevel and anothersecondlevel are defined as items and attribute are their respective attribute - value pairs

Valid characters for the items are a-z and A-Z plus any digit and underscore as second or further characters. Valid characters for the attributes are the same as for an item plus @ and *

lib.config.remove_comments(ydata, filename='')

Removes comments from a dict or OrderedDict structure

Parameter:

ydata (OrderedDict) – configuration (sub)tree to work on

lib.config.remove_digits(ydata, filename='')

Removes keys starting with digits from a dict or OrderedDict structure

Parameter:

ydata (OrderedDict) – configuration (sub)tree to work on

lib.config.remove_invalid(ydata, filename='')

Removes invalid chars in item from a dict or OrderedDict structure

Parameter:

ydata (OrderedDict) – configuration (sub)tree to work on

lib.config.remove_keys(ydata, func, remove=['attr'], level=0, msg=None, key_prefix='')

Removes given keys from a dict or OrderedDict structure

Parameter:

• ydata (OrderedDict) – configuration (sub)tree to work on

• func (function) – the function to call to check for removal (Example: lambda k: k.startswith(‚comment‘))

• level (int) – optional subtree level (used for recursion)

lib.config.remove_keyword(ydata, filename='')

Removes keys that are reserved Python keywords from a dict or OrderedDict structure

Parameter:

ydata (OrderedDict) – configuration (sub)tree to work on

lib.config.remove_reserved(ydata, filename='')

Removes keys that are reserved keywords from a dict or OrderedDict structure

Parameter:

ydata (OrderedDict) – configuration (sub)tree to work on

lib.config.remove_special_listentries(config, filename='')

lib.config.replace_struct_instance(path, subtree, instance)

Replace the constant string ‚@instance‘ in attribute names with the real instance (or remove the constant string ‚@instance‘, if the struct has no instace reference)

Parameter:

• path –

• subtree –

• instance –

Rückgabe:

lib.config.sanitize_items(ydata, filename='')

Remove all invalid entries from OrderedDict structure

Parameter:

ydata (OrderedDict) – configuration (sub)tree to work on

lib.config.search_for_struct_in_items(items, struct_dict, config, source_name='', parent='', level=0)

Test if the loaded file contains items with ‚struct‘ attribute.

This function is (recursively) called before merging the loaded file into the item tree

Parameter:

• items (OrderedDict) – tree content of a single items.yaml file (or part of it during recursion)

• struct_dict – dict with all defined structs (from /etc/structs.yaml and from loaded plugins)

• config (OrderedDict) – tree, into which the configuration should be merged

• parent –

Rückgabe:

True, if a struct attribute was expanded

lib.config.set_attr_for_subtree(subtree, attr, value, indent=0)

Parameter:

• subtree – dict (subtree) to operate on

• attr – Attribute to set for every item

• value – Value to set the attribute to

• indent – indent level (only for debug-logging)

Rückgabe:

lib.config.strip_quotes(string)

Strip single-quotes or double-quotes from string beggining and end

Parameter:

string (str) – String to strip the quotes from

Rückgabe:

Stripped string

Rückgabetyp:

str