lib.shyaml

This library does the handling of the configuration files of SmartHomeNG in yaml format. All file i/o from and to these configuration files goes through the functions which are implemented in this library.

Warning:

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

lib.shyaml.convert_linenumber(s, occ=1)

lib.shyaml.editing_is_enabled()

lib.shyaml.get_commentedseq(lst)

Convert a list to a commented sequence

lib.shyaml.get_emptynode()

Return an empty node

lib.shyaml.get_key(path)

lib.shyaml.get_parent(path)

lib.shyaml.setInDict(dataDict, path, value)

lib.shyaml.strip_yaml_extension(filename)

Strip a trailing .yaml or .yml (case-insensitive) from filename, if present. Callers are not always consistent about whether they pass a bare basename or one that already includes an extension - shng only ever reads/writes the .yaml form on disk, so this normalizes either input to the same basename.

Parameter:

filename (str) – Basename of a yaml file, with or without extension

Rückgabe:

filename with any trailing .yaml/.yml removed

Rückgabetyp:

str

lib.shyaml.writeBackToFile(filename, itempath, itemattr, value)

write the value of an item’s attribute back to the yaml-file

Parameter:

• filename – name of the yaml-file (without the .yaml extension!)

• itempath – path of the item to modify

• itemattr – name of the item’s attribute to modify

• value – new value for the attribute

Rückgabe:

formatted string

lib.shyaml.yaml_dump_roundtrip(data)

Dump yaml to a string using the RoundtripDumper and correct linespacing in output file

Parameter:

data – data structure to save

lib.shyaml.yaml_exists(filename)

Check whether the yaml file for filename exists on disk, regardless of whether filename already includes a .yaml/.yml extension or not.

A bare os.path.isfile(filename + YAML_FILE) silently returns False (making callers wrongly conclude „doesn’t exist yet“) when filename already ends in an extension, since it would then look for a nonexistent ...yaml.yaml path - this was the root cause of an existing item’s file being silently overwritten instead of loaded and merged into, whenever create_item()/rename_item() were handed a filename that still had its extension attached.

Parameter:

filename (str) – Basename of the yaml file, with or without extension

Rückgabe:

True if the file exists

Rückgabetyp:

bool

lib.shyaml.yaml_load(filename, ordered=False, ignore_notfound=False)

Load contents of a configuration file into an dict/OrderedDict structure. The configuration file has to be a valid yaml file

Parameter:

• filename (str) – name of the yaml file to load

• ordered (bool) – load to an OrderedDict? Default=False

Rückgabe:

configuration data loaded from the file (or None if an error occured)

Rückgabetyp:

Dict | OrderedDict | None

lib.shyaml.yaml_load_fromstring(string, ordered=False)

Load contents of a string into an dict/OrderedDict structure. The string has to be valid yaml

Parameter:

• string (str) – name of the yaml file to load

• ordered (bool) – load to an OrderedDict? Default=False

Rückgabe:

configuration data loaded from the file (or None if an error occured) and error string

Rückgabetyp:

Dict|OrderedDict|None, str

lib.shyaml.yaml_load_roundtrip(filename, raise_on_error=False)

Load contents of a yaml file into an dict structure for editing (using Roundtrip Loader)

Parameter:

• filename – name of the yaml file to load

• raise_on_error (bool) – if True, re-raise a load/parse failure instead of swallowing it into an empty dict. Callers that go on to MODIFY and SAVE the result must set this — treating a parse error the same as „file is legitimately empty“ makes the following save() silently truncate the file to just the one change being made, destroying everything else in it.

Rückgabe:

data structure loaded from file

lib.shyaml.yaml_save(filename, data)

Save contents of an OrderedDict structure to a yaml file

Parameter:

• filename (str) – name of the yaml file to save to

• data (OrderedDict, dict) – configuration data to to save

Rückgabe:

Nothing

lib.shyaml.yaml_save_roundtrip(filename, data, create_backup=False)

Dump yaml using the RoundtripDumper and correct linespacing in output file

Parameter:

• filename – name of the yaml file to save to

• data – data structure to save

class lib.shyaml.yamlfile(filename, filename_write='', create_bak=False)

Bases: object

data = None

filename = ''

getnode(path)

get the contents of a node (branch or leaf)

Parameter:

path – path of the node to return

Rückgabe:

content of the node

getnodetype(path)

get the type of a node

Parameter:

path – path of the node to return

Rückgabe:

node type (‚branch‘, ‚leaf‘ or ‚none‘)

getvalue(path)

get the value of a leaf-node

Parameter:

path – path of the node to return

Rückgabe:

value of the leaf (or None, if the node is no leaf-node)

getvaluetype(path)

get the valuetype of a node

Parameter:

path – path of the node to return

Rückgabe:

node valuetype

load()

load the contents of the yaml-file to the data-structure

A file whose root is literally null (e.g. after setvalue() removed its last top-level key) loads as None - normalize that to an empty CommentedMap, matching __init__’s default, so setvalue() doesn’t silently no-op on every subsequent call (None[key] = … raises TypeError, which setInDict() swallows and turns into a no-op).

Raises on a genuine parse failure (e.g. a duplicate-key error elsewhere in the file) rather than treating it the same as an empty file - this class is used to load, modify ONE value, and save the whole file back; silently continuing with empty data would make save() overwrite the rest of the file’s contents with nothing.

save()

save the contents of the data-structure to the yaml-file

If the data-structure is now empty (e.g. the last item defined in this file was removed), delete the file instead of writing a redundant {} document - an empty file and a „file with an empty mapping“ are equivalent for every reader in this codebase, so there’s nothing worth keeping.

setleafvalue(branch, leaf, value)

set the value of a leaf, specified by branch-path and attribute name

Parameter:

• branch – path of the branch-node which contains th attribute

• attr – name of the attribute to modify

• value – new value of the attribute

setvalue(path, value)

set the value of a leaf, specified by leaf-path

Parameter:

• path – path of the leaf-node to modify

• value – new value of the leaf-node