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, struct_attrs=None)

Add the referenced struct to the items_template subtree.

Supports both full struct names and partial sub-path references:

• struct: kodi.master — imports the whole kodi.master struct (existing behaviour)

• struct: kodi.master.bar — imports only the bar sub-tree of kodi.master

• struct: kodi.master.bar.child1 — imports a deeper sub-tree

When a partial path is used, the algorithm first checks whether a struct with the exact name exists (direct lookup). Only if that fails, it tries to find the longest registered struct name that is a prefix of the given name, then navigates into the struct tree along the remaining path components. This means that a struct literally named kodi.master.bar is never shadowed by the partial-path mechanism.

Errors are reported with context-specific messages:

• struct not found — no registered struct name matches any prefix of the given name.

• sub-item not found — a registered struct was found but the sub-path does not exist.

• not a sub-item tree — the sub-path resolves to a scalar attribute, not an item tree.

Parameter:

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

• struct_name (str) – Name (or partial path) of the struct to use for the item

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

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

• instance (str) – For multi-instance plugins: instance the items belong to

• struct_attrs (OrderedDict | None) – OrderedDict with attributes to propagate to every item in the struct

lib.config.merge(source, destination, source_name='', dest_name='', filename='', add=None, top=False)

Merges an OrderedDict Tree into another one

Parameter:

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

• destination (OrderedDict) – destination tree to merge into

• add (OrderedDict|None) – Data to insert into every node

• top (bool) – don’t add <add> if at top of tree

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, add=None)

Parameter:

• output_dict – dict structure to write to

• path – path to write to

• value – value to write to the nested key

• add – data to insert into every node

• top – at top of tree, don’t add <add> here

Rückgabe:

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

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 (Optional[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_itemsdir(itemsdir, item_conf, addfilenames=False, struct_dict=None)

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=None)

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=None, 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