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: MutableMapping[str, TNestedDictValue[TValue]] | None = None)

Bases: MutableMapping[str, TNestedDictValue], Generic

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 overwrite each other during initialization. For instance, NestedDict({'a.b': 1, 'a': {'b': 2}}) stores only one 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() → None

Removes all top-level entries from the mapping.

copy() → NestedDict[TValue]

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: str) → Self

Create an empty node at the given location.

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

Parameters:

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

Returns:

The leaf node

items(*, flatten: Literal[False] = False) → Iterator[tuple[str, TNestedDictValue[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: bool = False) → Iterator[str]

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: Any, flatten: bool = False, **kwargs: Any) → None

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.

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

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) → None

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.

update_recursive(other: MutableMapping[str, Any]) → None

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.

values(*, flatten: Literal[False] = False) → Iterator[TNestedDictValue[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]

type TDictTree = dict[str, TValue | TDictTree[TValue]]

type TNestedDictValue = TValue | NestedDict[TValue]