SDict

class dictIO.dict.SDict(**kwargs: V)

class dictIO.dict.SDict(arg: Mapping[K, V], **kwargs: V)

class dictIO.dict.SDict(arg: Iterable[tuple[K, V]], **kwargs: V)

class dictIO.dict.SDict(arg: str | PathLike[str], **kwargs: V)

Bases: dict[K, V]

Generic data structure for serializable dictionaries. Core class in dictIO.

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

__init__(**kwargs: V) → None

__init__(arg: Mapping[K, V], **kwargs: V) → None

__init__(arg: Iterable[tuple[K, V]], **kwargs: V) → None

__init__(arg: str | PathLike[str], **kwargs: V) → None

Methods

__init__()
clear()
copy()	Return a shallow copy of the SDict instance.
dump([target_file])	Dump the content of the current SDict instance into a dict file.
find_global_key([query])	Return the global key thread to the first key the value of which matches the passed in query.
fromkeys()	Create a new SDict instance from the keys of an iterable.
get(key[, default])	Return the value for key if key is in the dictionary, else default.
global_key_exists(global_key)	Check whether the specified global key exists.
include(dict_to_include)	Add an include directive for the passed in dict.
items()
keys()
load(source_file)	Load a dict file into this SDict instance.
merge(other)	Merge the passed in dict into the existing SDict instance.
order_keys()	alpha-numeric sorting of keys, recursively.
pop(k[,d])	If the key is not found, return the default if given; otherwise, raise a KeyError.
popitem()	Remove and return a (key, value) pair as a 2-tuple.
reduce_scope(scope)	Reduces the dict to the keys defined in scope.
reset()	Reset the dict.
set_global_key(global_key, value)	Set the value for the passed in global key.
setdefault(key[, default])	Insert key with a value of default if key is not in the dictionary.
update()	Update top-level keys with the keys from the passed in dict.
values()

Attributes

data	Mimick the data property of the CppDict class from dictIO <= v0.3.4.
name	Return the name of the source file of the SDict instance.
path	Return the path of the source file of the SDict instance.
source_file	Return the source file of the SDict instance.
variables	Returns a dict with all Variables currently registered.

copy() → SDict[K, V]

Return a shallow copy of the SDict instance.

Returns:

shallow copy of the SDict instance

Return type:

SDict[K, V]

dump(target_file: str | PathLike[str] | None = None) → Path

Dump the content of the current SDict instance into a dict file.

Following file formats are supported and interpreted through target_file’s file ending: no file ending -> dictIO native dict file ‘.cpp’ -> dictIO native dict file ‘.foam’ -> Foam dictionary file ‘.json’ -> Json dictionary file ‘.xml’ -> XML file

Parameters:

target_file (Union[str, os.PathLike[str], None], optional) – target dict file name, by default None

Returns:

target dict file

Return type:

Path

Raises:

ValueError – if target_file was not specified while the current SDict instance has no source file set (and hence the target file cannot be inferred).

find_global_key(query: str = '') → list[K | int] | 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:

list[K | int] | None

classmethod fromkeys(iterable: Iterable[_K], value: None = None) → SDict[_K, Any | None]

classmethod fromkeys(iterable: Iterable[_K], value: _V) → SDict[_K, _V]

Create a new SDict instance from the keys of an iterable.

Parameters:

• iterable (Iterable[_K]) – An iterable with keys

• value (_V | None, optional) – The value to be assigned to the passed in keys, by default None

Returns:

The created SDict instance.

Return type:

SDict[_K, _V] | SDict[_K, Any | None]

global_key_exists(global_key: MutableSequence[K | int]) → bool

Check whether the specified global key exists.

Parameters:

global_key (MutableSequence[K | int]) – global key the existence of which is checked

Returns:

True if the specified global key exists, otherwise False

Return type:

bool

include(dict_to_include: SDict[_K, _V]) → None

Add an include directive for the passed in dict.

Parameters:

dict_to_include (SDict) – 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

load(source_file: str | PathLike[str]) → SDict[K, V]

Load a dict file into this SDict instance.

Reads a dict file and loads its content into the current SDict instance. The content of the current SDict instance will be overwritten.

Following file formats are supported and interpreted through source_file’s file ending: no file ending -> dictIO native dict file ‘.cpp’ -> dictIO native dict file ‘.foam’ -> Foam dictionary file ‘.json’ -> Json dictionary file ‘.xml’ -> XML file

Parameters:

source_file (Union[str, os.PathLike[str]]) – dict file to be loaded

Returns:

self

Return type:

SDict[K, V]

Raises:

FileNotFoundError – if source_file does not exist

merge(other: Mapping[K, V]) → None

Merge the passed in dict into the existing SDict 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:

other (Mapping[K, V]) – dict to be merged

order_keys() → None

alpha-numeric sorting of keys, recursively.

reduce_scope(scope: MutableSequence[K]) → None

Reduces the dict to the keys defined in scope.

Parameters:

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

reset() → None

Reset the dict.

Removes all items from the dict.

set_global_key(global_key: MutableSequence[K | int], value: V) → 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[K | int]) – list of keys defining the global key thread to the target key (such as returned by method find_global_key())

• value (V) – value the target key shall be set to

update(m: Mapping[K, V], **kwargs: V) → None

update(m: Iterable[tuple[K, V]], **kwargs: V) → None

update(**kwargs: V) → 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 SDict 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[K, V] | Iterable[tuple[K, V]] | None) – dict containing the keys to be updated and its new values

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

property data: dict[K, V]

Mimick the data property of the CppDict class from dictIO <= v0.3.4.

Mimicks the data property of the deprecated CppDict class to maintain backward compatibility. This property is deprecated and will be removed with v0.5.0.

Returns:

the content of the SDict instance

Return type:

dict[K, V]

property name: str

Return the name of the source file of the SDict instance.

Returns:

name of the source file of the SDict instance

Return type:

str

property path: Path

Return the path of the source file of the SDict instance.

Returns:

path of the source file of the SDict instance

Return type:

Path

property source_file: Path | None

Return the source file of the SDict instance.

Returns:

source file of the SDict instance

Return type:

Path or None

property variables: dict[str, V]

Returns a dict with all Variables currently registered.

Returns:

dict of all Variables currently registered.

Return type:

Dict[str, V]