ddp_utils.udict

import ddp_utils.udict

Dictionary merge, key selection, predicate lookup and in-place updates.

Examples

Use this public operation:

import ddp_utils.udict

ddp_utils.udict.merge_by_template(dst: Dict[str, Any], src: Dict[str, Any]) → bool

Update dst recursively from src, preserving keys found only in dst.

Missing keys are inserted; unequal non-dict values are replaced. Recursion occurs only when both values are dicts. Assigned values are shared references, not deep copies. Cyclic nested mappings are not specially handled.

Parameters

Name	Type	Description
dst	Dict[str, Any]	Destination dict, mutated in place.
src	Dict[str, Any]	Template dict; its values take precedence on shared keys.

Returns

Type	Description
bool	True if any insertion or replacement occurred, otherwise False.

Examples

Use this public operation:

result = ddp_utils.udict.merge_by_template(dst=dst_value, src=src_value)

ddp_utils.udict.diff_keys(a: Dict[str, Any], b: Dict[str, Any]) → Dict[str, set]

Compare top-level key sets without comparing values or mutating inputs.

Parameters

Name	Type	Description
a	Dict[str, Any]	First dictionary.
b	Dict[str, Any]	Second dictionary.

Returns

Type	Description
Dict[str, set]	Dictionary containing the "only_in_a", "only_in_b", and "common" key sets.

Examples

Use this public operation:

result = ddp_utils.udict.diff_keys(a=a_value, b=b_value)

ddp_utils.udict.pick(src: Dict[str, Any], *keys: str) → Dict[str, Any]

Return a shallow dictionary containing requested keys that exist in src.

Parameters

Name	Type	Description
src	Dict[str, Any]	Source dictionary, not modified.
*keys	str	Keys to include, in output insertion order; absent keys are skipped.

Returns

Type	Description
Dict[str, Any]	New dictionary sharing the source values; no keys returns {}.

Examples

Use this public operation:

result = ddp_utils.udict.pick(src=src_value)

ddp_utils.udict.omit(src: Dict[str, Any], *keys: str) → Dict[str, Any]

Return a shallow dictionary excluding the requested keys.

Parameters

Name	Type	Description
src	Dict[str, Any]	Source dictionary, not modified; its key order is preserved.
*keys	str	Keys to omit; absent keys have no effect.

Returns

Type	Description
Dict[str, Any]	New dictionary sharing retained values; no keys returns a shallow copy.

Examples

Use this public operation:

result = ddp_utils.udict.omit(src=src_value)

ddp_utils.udict.find_dict_in_list(data, condition)

Return the first matching original dictionary, or None.

Dict conditions compare item.get(key) to each value. Thus a missing key matches an expected None, and {} matches the first item. A callable uses truthiness of condition(item). Unsupported condition types yield no match.

Parameters

Name	Description
data	Iterable of dictionaries, searched in order without mutation.
condition	Dict of expected fields, or callable accepting one item.

Returns

Original matching dictionary (not a copy), or None. Predicate errors propagate.

Examples

Use this public operation:

result = ddp_utils.udict.find_dict_in_list(data=data_value, condition=condition_value)

ddp_utils.udict.find_index_of_dict(data, condition)

Return the zero-based index of the first match, or None.

Matching follows find_dict_in_list: dict fields use item.get, {} matches the first item, callable results use truthiness, and unsupported types return None. Predicate exceptions propagate. Index 0 is a valid result.

Parameters

Name	Description
data	Iterable of dictionaries, searched in order.
condition	Dict of expected fields or callable accepting one item.

Returns

Integer index, or None for empty input or no match.

Examples

Use this public operation:

result = ddp_utils.udict.find_index_of_dict(data=data_value, condition=condition_value)

ddp_utils.udict.find_dict_and_index(data, condition)

Return the first matching original dictionary together with its index.

Matching follows find_dict_in_list, including missing-key/None equivalence, empty-condition matching and propagation of predicate exceptions.

Parameters

Name	Description
data	Iterable of dictionaries searched in order.
condition	Dict of expected fields or callable accepting one item.

Returns

(original_dictionary, zero_based_index), or (None, None) for no match.

Examples

Use this public operation:

result = ddp_utils.udict.find_dict_and_index(data=data_value, condition=condition_value)

ddp_utils.udict.find_in_list_and_update(data, condition, updates, update_all=False)

Update matching dictionaries in place and return data plus matched indexes.

Matching uses the same dict/callable rules as find_dict_in_list. Updates are shallow dict.update operations, not recursive merges. Earlier updates remain applied if a later predicate or update raises.

Parameters

Name	Description
data	Mutable list of dictionaries; the returned list is this same object.
condition	Dict of expected fields or callable accepting one item.
updates	Values applied with dict.update to each selected dictionary.
update_all	False changes only the first match; True visits all matches.

Returns

(data, list_of_indexes), or (data, None) if nothing matched. Matching indexes are reported even when updates is empty or values do not change.

Raises

Exception	Description
TypeError	condition is neither a dict nor callable and data is nonempty. Empty input does not evaluate or validate the condition.

Examples

Use this public operation:

result = ddp_utils.udict.find_in_list_and_update(data=data_value, condition=condition_value, updates=updates_value)