4.7.11 pde.tools.nested_dict module

Provides a nested dictionary that stores hierarchical mappings.

NestedDict

Stores hierarchical mappings with string paths as keys.

class NestedDict(data=None)

Bases: MutableMapping[str, TValue | NestedDict[TValue]], Generic[TValue]

Stores hierarchical mappings with string paths as keys.

NestedDict wraps nested mappings and supports reading and writing nested values using a separator-based key syntax (for example "a.b.c"). It can convert between flat and nested representations and recursively traverses children when requested.

Note

Equivalent entries can overwrite each other during initialization. For instance, NestedDict({'a.b': 1, 'a': {'b': 2}}) stores only one final value for a.b.

Initializes a nested dictionary from an optional mapping.

Parameters:

data (MutableMapping[str, Any] | None) – Optional mapping used to populate the instance. Nested plain dictionaries are converted into NestedDict children.

clear()

Removes all top-level entries from the mapping.

Return type:

None

copy()

Creates a structural copy with copied nested mappings.

Child dictionaries and child NestedDict instances are copied, while non-mapping leaf values are reused by reference.

Returns:

New instance containing copied nested structure.

Return type:

NestedDict

create_node(key)

Create an empty node at the given location.

Creates all necessary parent nodes recursively. Skips nodes that already exist.

Parameters:

key (str) – Key or nested key path identifying the node to create.

Returns:

The leaf node

Return type:

Self

data: MutableMapping[str, TValue | NestedDict[TValue]]

Internal mapping storing top-level keys and values for this instance.

Type:

dict

items(*, flatten: Literal[False] = False) → Iterator[tuple[str, TValue | NestedDict[TValue]]]

items(*, flatten: Literal[True]) → Iterator[tuple[str, TValue]]

Iterates over key-value pairs, optionally flattening nested paths.

Parameters:

flatten (bool) – If True, yields (path, value) pairs for all descendants. If False, yields only top-level pairs.

Returns:

Iterator over key-value pairs according to flatten.

Return type:

Iterator[tuple[str, Any]]

Raises:

TypeError – If a key used during flattening is not a string.

keys(*, flatten=False)

Iterates over keys, optionally returning flattened key paths.

Parameters:

flatten (bool) – If True, yields separator-joined paths for descendant keys. If False, yields only top-level keys.

Returns:

Iterator over keys or flattened key paths.

Return type:

Iterator[str]

Raises:

TypeError – If a key used during flattening is not a string.

pprint(*args, flatten=False, **kwargs)

Pretty-prints the current data as nested plain dictionaries.

Parameters:

• *args (Any) – Positional arguments forwarded to pprint.pprint.

• flatten (bool) – If True, returns a flat mapping with separator-joined paths as keys. If False, returns nested dictionaries.

• **kwargs (Any) – Keyword arguments forwarded to pprint.pprint.

Return type:

None

sep: str = '.'

Separator used in key paths to traverse nested levels.

Type:

str

to_dict(*, flatten: Literal[False] = False) → dict[str, TValue | TDictTree]

to_dict(*, flatten: Literal[True]) → dict[str, TValue]

Converts this object to a plain dictionary representation.

Parameters:

flatten (bool) – If True, returns a flat mapping with separator-joined paths as keys. If False, returns nested dictionaries.

Returns:

Dictionary representation of this object.

Return type:

dict[str, Any]

Raises:

TypeError – If flattening encounters non-string keys.

update(other)

Update this mapping from another mapping recursively.

This method implements collections.abc.MutableMapping update semantics for mapping-like inputs and forwards the actual merge to update_recursive().

Parameters:

other – Mapping containing keys and values to merge into this instance.

Raises:

TypeError – If other is not a mutable mapping.

Return type:

None

update_recursive(other)

Recursively merges another mapping into this instance.

Parameters:

other (MutableMapping[str, Any]) – Mapping whose entries are merged into this object. If both sides contain nested mappings at a key, values are merged recursively.

Return type:

None

values(*, flatten: Literal[False] = False) → Iterator[TValue | NestedDict[TValue]]

values(*, flatten: Literal[True]) → Iterator[TValue]

Iterates over values, optionally recursing into nested children.

Parameters:

flatten (bool) – If True, yields values from all descendant NestedDict instances. If False, yields only top-level values.

Returns:

Iterator over values according to flatten.

Return type:

Iterator[Any]