dictIO.cppDict module#

class dictIO.cppDict.CppDict(file: str | PathLike[str] | None = None)#

Bases: UserDict[Any, Any]

Data structure for generic dictionaries.

CppDict inherits from UserDict. It can hence be used transparently also in a context where a dict or any other MutableMapping type is expected.

include(dict_to_include: CppDict)#

Add an include directive for the passed in dict.

Parameters:

dict_to_include (CppDict) – The dict to be included via an include directive

Raises:

  • AttributeError – If dict_to_include.source_file is None

  • ValueError – If no relative path in between the current dict and the included dict can be resolved

update(_CppDict__m: Mapping[Any, Any], **kwargs: Any) → None#

Update top-level keys with the keys from the passed in dict.

Overrides the update() method of UserDict base class in order to include also CppDict class attributes in the update.

If a key already exists, it will be substituted by the key from the passed in dict. In order to not substitute top-level keys but recursively merge (potentially nested) content from passed in dict into the existing, use merge() instead.

Note:

The behaviour of update() corresponds with default mode ‘-w’ in the dictParser command line interface.

The behaviour of merge() corresponds with mode ‘-a’ in the dictParser command line interface. See also CLI Documentation.

Parameters:

  • __m (Mapping) – dict containing the keys to be updated and its new values

  • **kwargs (Any) – optional keyword arguments. These will be passed on to the update() method of the parent class.

merge(dict: MutableMapping[Any, Any])#

Merge the passed in dict into the existing CppDict instance.

In contrast to update(), merge() works recursively. That is, it does not simply substitute top-level keys but recursively merges (potentially nested) content from the passed in dict into the existing. This prevents nested keys from being deleted. Further, existing keys will NOT be overwritten.

Parameters:

dict (MutableMapping[Any, Any]) – dict to be merged

order_keys()#

alpha-numeric sorting of keys, recursively.

find_global_key(query: str = '') → List[Any] | None#

Return the global key thread to the first key the value of which matches the passed in query.

Function works recursively on nested dicts and is non-greedy: The key of the first match is returned. Return value is a sequence of keys: The ‘global key thread’. It represents the sequence of keys that one needs to traverse downwards in order to arrive at the target key found.

Parameters:

query (str, optional) – query string for the value to search for by default ‘’

Returns:

global key thread to the first key the value of which matches the passed in query, if found. Otherwise None.

Return type:

Union[List[Any], None]

set_global_key(global_key: MutableSequence[Any], value: Any = None)#

Set the value for the passed in global key.

The global key thread is traversed downwards until arrival at the target key, the value of which is then set.

Parameters:

  • global_key (MutableSequence[Any]) – list of keys defining the global key thread to the target key (such as returned by method find_global_key())

  • value (Any, optional) – value the target key shall be set to, by default None

global_key_exists(global_key: MutableSequence[Any]) → bool#

Check whether the specified global key exists.

Parameters:

global_key (MutableSequence[Any]) – global key the existence of which is checked

Returns:

True if the specified global key exists, otherwise False

Return type:

bool

reduce_scope(scope: MutableSequence[str])#

Reduces the dict to the keys defined in scope.

Parameters:

scope (MutableSequence[str]) – scope the dict shall be reduced to

property variables: Dict[str, Any]#

Returns a dict with all Variables currently registered.

Returns:

dict of all Variables currently registered.

Return type:

Dict[str, Any]

dictIO.cppDict.order_keys(arg: MutableMapping[_KT, _VT]) → Dict[_KT, _VT]#

alpha-numeric sorting of keys, recursively.

Parameters:

arg (MutableMapping[_KT, _VT]) – dict, the keys of which shall be sorted

Returns:

passed in dict with keys sorted

Return type:

Dict[_KT, _VT]

dictIO.cppDict.find_global_key(arg: MutableMapping[Any, Any] | MutableSequence[Any], query: str = '') → List[Any] | None#

Return the global key thread to the first key the value of which matches the passed in query.

Parameters:

  • arg (Union[MutableMapping[Any, Any], MutableSequence[Any]]) – dict to search in for the queried value

  • query (str, optional) – query string for the value to search for, by default ‘’

Returns:

global key thread to the first key the value of which matches the passed in query, if found. Otherwise None.

Return type:

Union[List, None]

dictIO.cppDict.set_global_key(arg: MutableMapping[Any, Any], global_key: MutableSequence[Any], value: Any = None)#

Set the value for the passed in global key.

Parameters:

  • arg (MutableMapping[Any, Any]) – dict the target key in which shall be set

  • global_key (MutableSequence[Any], optional) – list of keys defining the global key thread to the target key (such as returned by method find_global_key())

  • value (Any, optional) – value the target key shall be set to, by default None

dictIO.cppDict.global_key_exists(arg: MutableMapping[Any, Any], global_key: MutableSequence[Any]) → bool#

Check whether the specified global key exists in the passed in dict.

Parameters:

  • arg (MutableMapping[Any, Any]) – dict to check for existence of the specified global key

  • global_key (MutableSequence[Any], optional) – global key the existence of which is checked in the passed in dict

Returns:

True if the specified global key exists, otherwise False

Return type:

bool