gwadama.dictools#
dictools.py
Collection of utility functions related to nested Python dictionaries.
- gwadama.dictools.dict_to_stacked_array(dict_: dict, target_length: int | None = None) tuple[ndarray, list][source]#
Stack the arrays inside a dict() to a 2d-array.
Given a NON-nested dict whose values are flat numpy arrays, with potentially different lengths, stacks them in a homogeneous 2d-array aligned to the left, zero-padding the remaining space.
- Parameters:
- dict_dict[str: np.ndarray]
NON-nested Python dictionary containing numpy 1d-arrays.
- target_lengthint, optional
If given, defines the size of the second axis of the returned 2d-array. If omitted, the size will be equal to the longest array inside ‘dict_’. Must be larger or equal than the longest array inside ‘dict_’.
- Returns:
- stacked_arrays2d-array
Stacked arrays, with right zero-padding those original strains whose length were shorter.
- lengthslist
Original length of each input array, following the same order as the first axis of ‘stacked_arrays’.
- gwadama.dictools.fill(dict_: dict, value, keys=None, deepcopy=False)[source]#
Fill an arbitrarily-depth nested dictionary with a value.
Fill an arbitrarily-depth nested dictionary below the coordinates ‘keys’ with the value ‘value’.
The filling is performed inplace.
- Parameters:
- dict_: dict
Nested dictionary.
- value: Any
- keys: iterable, optional
Starting layers from where to fill the dictionary, if only a subset of the whole ‘dict_’ is desired to be filled.
- deepcopy: bool
If True, each instance of ‘value’ will be a copy. By default all elements reference the same ‘value’.
- gwadama.dictools.filter_nested_dict(dict_, condition, layer) dict[source]#
Filter a layer of a nested dictionary.
Filter a nested dictionary based on a condition applied to the keys of the specified layer.
NOTE: Layer numbering begins with 0, as array-likes do; as God commands.
- Parameters:
- dict_dict
The nested dictionary to be filtered.
- conditioncallable
The condition function to apply. Should take a single argument, the key, and return a boolean indicating wether to include its related value.
- layerint
The layer at which to apply the condition. 1 corresponds to the top level, 2 to the second level, and so on. Default is 1.
- Returns:
- : dict
Filtered version of the nested dictionary.
- gwadama.dictools.find_parent_key_of_nested_key(dict_, key: int | str) int | str[source]#
Finds the top level key containing the second level ‘key’.
Finds the key of the uppermost level of the nested ‘dict_’ which contains the second level entry with key ‘key’.
- gwadama.dictools.flatten_nested_dict(dict_: dict) dict[source]#
Turn any nested dictionary into a shallow (single level) one.
Flatten a nested dictionary into a single level dictionary, keeping their keys as tuples.
- gwadama.dictools.get_depth(dict_: dict) int[source]#
Return the depth of the input nested dictionary.
A simple (non-nested) dictionary has a depth of 1. Assumes a homogeneous nested dictionary, and only looks for the first element at each layer.
- gwadama.dictools.get_first_value(dict_)[source]#
Get the first value in a nested dictionary.
If dict_ is not a python dictionary, the argument is returned as is.
- Returns:
- valueAny
Next value in dict_.
- gwadama.dictools.get_number_of_elements(dict_)[source]#
Get the number of elements in a nested dictionary.
- Parameters:
- dict_dict
Nested dictionary.
- Returns:
- numberint
Number of elements in the nested dictionary.
- gwadama.dictools.get_types(d: dict)[source]#
Get all element types in a nested dictionary.
Return all unique non-dict types from values in a (possibly nested) dictionary.
- Parameters:
- ddict
Input dictionary.
- Returns:
- typesset
Set of non-dict Python types.
- gwadama.dictools.get_value_from_nested_dict(dict_: dict, keys: Iterable[Any]) Any[source]#
Access a value from a nested dictionary using a sequence of keys.
- Parameters:
- dict_dict
A dictionary which may contain further nested dictionaries.
- keysiterable
A sequence of keys that defines the path to the target value.
- Returns:
- Any
The value located at the nested key path.
Warning
The returned value is the original object stored in the dictionary and can be modified in-place. Use this behaviour with caution.
Notes
This function only traverses Python dict objects. If a path segment encounters a non-dict (e.g., a NumPy array), a KeyError is raised. This prevents accidental array indexing when a path is malformed.
- gwadama.dictools.replicate_structure(dict_: dict) dict[source]#
Create a new nested dictionary with the same structure as the input.
Values of the new dictionary are set to None.
- gwadama.dictools.set_value_to_nested_dict(dict_: dict, keys: Iterable[Any], value: Any, *, add_missing_keys=False) None[source]#
Set a value in a nested dictionary using a sequence of keys.
- Parameters:
- dict_: dict
Target nested dictionary.
- keys: iterable
Sequence of keys necessary to reach the element inside the nested dictionary.
- value: Any
Value to set at the target location.
- add_missing_keys: bool
If True, missing intermediate keys are created as empty dicts. If False (default), a missing key raises KeyError.
- Raises:
- TypeError
If dict_ is not a dictionary.
- KeyError
If an intermediate key is missing (and add_missing_keys is False), or if a non-dict object is encountered before the final key.
Notes
This function only creates/traverses plain dict containers.
It refuses to descend into non-dict objects, avoiding accidental array
indexing or attribute misuse mid-path.
- gwadama.dictools.unroll_nested_dictionary_keys(dict_: dict, max_depth: int | None = None) list[source]#
Returns a list of all combinations of keys inside a nested dictionary.
Useful to iterate over all keys of a nested dictionary without having to use multiple loops.
- Parameters:
- dictionary: dict
Nested dictionary.
- max_depth: int, optional
If specified, it is the number of layers to dig in to at most in the nested dictionary. If only the first layer is desired (no recursion at all), max_depth=1.
- Returns:
- : list
Unrolled combinations of all keys of the nested dictionary.