dict_utils#

Utility functions and classes for manipulating dictionaries in KnotPy.

Includes comparison utilities, inversion helpers (flat, multi, nested), and lazy/identity/classifier dict variants.

Functions

`common_dict`(*dicts)	Find key/value pairs shared across all provided dictionaries.
`compare_dicts`(dict1, dict2[, exclude_keys, ...])	Recursively compare two dictionaries with optional key filters.
`invert_dict`(d)	Invert a dictionary with unique values.
`invert_dict_of_sets`(d)	Invert a dictionary of sets.
`invert_multi_dict`(d)	Invert a dictionary, grouping keys by shared values.
`invert_nested_dict`(d)	Group keys by their nested dictionary value signatures.

Classes

`ClassifierDict`(functions)	Dictionary that groups items by a tuple of classifier function outputs.
`IdentityDict`()	A `defaultdict` that returns the key itself as the default.
`LazyDict`(load_function[, eval_function])	Dictionary that supports lazy loading and optional lazy value evaluation.

compare_dicts(dict1, dict2, exclude_keys=None, include_only_keys=None)#

Recursively compare two dictionaries with optional key filters.

Comparison order:

Effective key sets (after include/exclude),
Values under those keys (recursing into nested dicts),
Sets are compared via sorted order, other values via native ordering.

Parameters:

dict1 (dict[str, Any]) – First dictionary to compare.
dict2 (dict[str, Any]) – Second dictionary to compare.
exclude_keys (Iterable[str] | None) – Keys to ignore at the top level.
include_only_keys (Iterable[str] | None) – If provided, only these top-level keys are considered.

Returns:

1 if dict1 > dict2, -1 if dict1 < dict2, 0 if equal.

Raises:

TypeError – If corresponding values have mismatched types and cannot be compared.

Return type:

int

invert_dict(d)#

Invert a dictionary with unique values.

Parameters:: d (dict[K, V]) – Input mapping with unique values.
Returns:: Inverse mapping from value to key.
Raises:: ValueError – If a duplicate value is encountered.
Return type:: dict[V, K]

invert_multi_dict(d)#

Invert a dictionary, grouping keys by shared values.

Parameters:: d (dict[K, V]) – Input mapping (values need not be unique).
Returns:: Mapping from value to set of keys that mapped to it.
Return type:: dict[V, set[K]]

invert_dict_of_sets(d)#

Invert a dictionary of sets.

Parameters:: d (dict[K, set[V]]) – Mapping where values are sets.
Returns:: Inverse mapping value -> set of original keys.
Return type:: dict[V, set[K]]

invert_nested_dict(d)#

Group keys by their nested dictionary value signatures.

Parameters:: d (dict[K, dict[str, Any]]) – Mapping whose values are nested dicts.
Returns:: Mapping from tuples of inner values (ordered by inner key name) to sets of outer keys.
Return type:: dict[tuple[Any, …], set[K]]

class LazyDict(load_function, eval_function=None, *args, **kwargs)#

Bases: dict[K, V], Generic[K, V]

Dictionary that supports lazy loading and optional lazy value evaluation.

Parameters:

load_function (Callable[[], dict[K, V] | Iterable[tuple[K, V]]]) – Callable returning either a dict or an iterable of (key, value) pairs.
eval_function (Callable[[V], V] | None) – Optional callable applied to values on first access (per key).
args (Any)
kwargs (Any)

Example

>>> def load(): return {"a": "2 + 2"}
>>> def evaluate(expr): return eval(expr)
>>> d = LazyDict(load, evaluate)
>>> d["a"]
4

keys() → a set-like object providing a view on D's keys#

values() → an object providing a view on D's values#

items() → a set-like object providing a view on D's items#

get(key, default=None)#

Return the value for key if key is in the dictionary, else default.

Parameters:

key (K)
default (V | None)

Return type:

V | None

reload()#

Reload the dictionary using the original load function.

Clears existing values and evaluation state, then loads fresh data.

Return type:: None

class IdentityDict#

Bases: defaultdict[K, K]

A defaultdict that returns the key itself as the default.

Example

>>> d = IdentityDict()
>>> d["x"]
'x'

class ClassifierDict(functions)#

Bases: dict[tuple[Any, …], list[T]], Generic[T]

Dictionary that groups items by a tuple of classifier function outputs.

Parameters:: functions (dict[str, Callable[[T], Any]]) – Mapping label -> function(item) used to compute the grouping key.

append(item)#

Group the given item under a key defined by its classification values.

Parameters:: item (T) – The item to group.
Return type:: None

common_dict(*dicts)#

Find key/value pairs shared across all provided dictionaries.

Parameters:: *dicts (dict[str, Any]) – One or more dictionaries.
Returns:: Dictionary of pairs present and equal in all inputs.
Return type:: dict[str, Any]

Example

>>> common_dict({'a': 1}, {'a': 1, 'b': 2}, {'a': 1})
{'a': 1}