dictIO.utils.dict

Utility functions for working with dictionaries.

Functions

find_global_key(arg[, query])	Return the global key thread to the first key the value of which matches the passed in query.
global_key_exists(dict_in, global_key)	Check whether the specified global key exists in the passed in dict.
order_keys(arg)	Sort mapping keys recursively, placing non-string keys before strings.
set_global_key(arg, global_key, value)	Set a value at the location identified by a global key path.

dictIO.utils.dict.find_global_key(arg: MutableMapping[K, V] | MutableSequence[V], query: str = '') → list[K | int] | None

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

The query is interpreted as a regular expression and values are searched in traversal order.

Parameters:

• arg (MutableMapping[K, V] | MutableSequence[V]) – Nested mapping or sequence to search.

• query (str) – Regular expression to search for in each value’s string form. Defaults to “”.

Returns:

The key path to the first matching value, or None if no value matches.

Return type:

list[K | int] | None

dictIO.utils.dict.global_key_exists(dict_in: MutableMapping[K, V], global_key: MutableSequence[K | int]) → bool

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

Each key in the path must lead to another mapping; a scalar value at an intermediate level means the path does not exist.

Parameters:

• dict_in (MutableMapping[K, V]) – Mapping to search.

• global_key (MutableSequence[K | int]) – Key path whose existence is checked.

Returns:

True if the path exists through nested mappings, otherwise False.

Return type:

bool

dictIO.utils.dict.order_keys(arg: M) → M

Sort mapping keys recursively, placing non-string keys before strings.

The mapping is updated in place, and the same instance is returned.

Parameters:

arg (M) – Mapping whose keys should be sorted.

Returns:

The input mapping with recursively sorted keys.

Return type:

M

dictIO.utils.dict.set_global_key(arg: MutableMapping[K, V], global_key: Sequence[K | int], value: V) → None

Set a value at the location identified by a global key path.

An empty key path leaves the mapping unchanged. Paths may traverse nested mappings and sequences, and are limited to ten levels.

Parameters:

• arg (MutableMapping[K, V]) – Mapping containing the target location.

• global_key (Sequence[K | int]) – Key path to the target location, such as one returned by find_global_key.

• value (V) – Value to store at the target location.

Raises:

• KeyError – If the key path is invalid or does not identify a nested mapping or sequence.

• RecursionError – If the path traverses more than ten levels.

Return type:

None