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.

Parameters:

• arg (Mapping[K, V] | Iterable[tuple[K, V]] | str | os.PathLike[str] | None)

• kwargs (V)

counter

Counter used to create unique keys for parser metadata.

source_file

Source file associated with this dictionary, or None if unset.

path

Parent directory of source_file, or the current working directory if unset.

name

Name of source_file, or an empty string if unset.

line_content

Source lines retained while parsing.

block_content

Source text retained while parsing.

tokens

Tokens retained while parsing.

string_literals

String literals retained while parsing.

expressions

Expressions parsed from the source file.

line_comments

Line comments parsed from the source file.

block_comments

Block comments parsed from the source file.

includes

Include directives parsed from the source file.

brackets

Opening and closing bracket pairs recognized by the parser.

delimiters

Characters that separate dictionary elements.

openingBrackets

Opening bracket characters recognized by the parser.

closingBrackets

Closing bracket characters recognized by the parser.

variables

Values exposed through the dictionary’s variable lookup.

data

Deprecated alias for the dictionary content.

__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

Initialize a dictionary, optionally associating it with a source file.

Parameters:

• arg (Mapping[K, V] | Iterable[tuple[K, V]] | str | PathLike[str] | None) – Initial mapping, key-value iterable, or source file. If None, initialize an empty dictionary. Defaults to None.

• **kwargs (V) – Additional entries to initialize the dictionary with.

Return type:

None

Methods

__init__(-> None -> None -> None)	Initialize a dictionary, optionally associating it with a source file.
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(-> None -> None)	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.

classmethod fromkeys(iterable: Iterable[_K], value: None = None) → SDict[_K, 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) – Value assigned to each key. If None, each key is mapped to None. Defaults to None.

Returns:

The created SDict instance.

Return type:

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

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 (str | PathLike[str] | None) – Target file name. If None, use the source file associated with this instance; if no source file is set, raise ValueError. Defaults to None.

Returns:

Path to the written dictionary file.

Raises:

ValueError – If target_file is None and this instance has no source file from which to infer the target.

Return type:

Path

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) – Value to search for. Defaults to “”.

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

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[_K, _V]) – 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

Return type:

None

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 (str | PathLike[str]) – dict file to be loaded.

Returns:

This dictionary instance after its content has been replaced by the file contents.

Raises:

FileNotFoundError – If source_file does not exist.

Return type:

SDict[K, V]

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]) – Mapping whose entries are recursively merged into this dictionary.

Return type:

None

order_keys() → None

alpha-numeric sorting of keys, recursively.

Return type:

None

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.

Return type:

None

reset() → None

Reset the dict.

Removes all items from the dict.

Return type:

None

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]) – Keys defining the path to the target key, such as the sequence returned by find_global_key().

• value (V) – Value to assign to the target key.

Return type:

None

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 behavior of update() corresponds with default mode -w in the dictParser command line interface.

The behavior of merge() corresponds with mode -a in the dictParser command line interface. See the CLI documentation.

Parameters:

• m (Mapping[K, V] | Iterable[tuple[K, V]] | None) – Mapping or iterable of key-value pairs to update. If None, no entries are taken from this argument. Defaults to None.

• **kwargs (V) – Additional entries to update.

Return type:

None

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

property name: str

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

Returns:

Name of the associated source file, or an empty string if no source file is set.

property path: Path

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

Returns:

Parent directory of the associated source file, or the current working directory if no source file is set.

property source_file: Path | None

Return the source file of the SDict instance.

Returns:

Source file associated with this dictionary, or None if unset.

property variables: dict[str, V]

Returns a dict with all Variables currently registered.

Returns:

dict of all Variables currently registered.