hdx.utilities.dictandlist

module hdx.utilities.dictandlist

Dict and List utilities.

Functions

invert_dictionary — Invert a dictionary from key - value to value - key. Assumes one to one mapping between keys and values.
merge_two_dictionaries — Merges b into a and returns merged result.
merge_dictionaries — Merges all dictionaries in dicts into a single dictionary and returns result.
dict_diff — Compares two dictionaries.
dict_of_lists_add — Add value to a list in a dictionary by key.
dict_of_sets_add — Add value to a set in a dictionary by key.
dict_of_dicts_add — Add key value pair to a dictionary within a dictionary by key.
list_distribute_contents_simple — Distribute the contents of a list eg. [1, 1, 1, 2, 2, 3] -> [1, 2, 3, 1, 2, 1]. List can contain complex types like dictionaries in which case the function can return the appropriate value eg. lambda x: x[KEY]
list_distribute_contents — Distribute the contents of a list eg. [1, 1, 1, 2, 2, 3] -> [1, 2, 1, 2, 1, 3]. List can contain complex types like dictionaries in which case the function can return the appropriate value eg. lambda x: x[KEY]
extract_list_from_list_of_dict — Extract a list by looking up key in each member of a list of dictionaries.
key_value_convert — Convert keys and/or values of dictionary using functions passed in as parameters.
integer_key_convert — Convert keys of dictionary to integers.
integer_value_convert — Convert values of dictionary to integers.
float_value_convert — Convert values of dictionary to floats.
avg_dicts — Create a new dictionary from two dictionaries by averaging values.
read_list_from_csv — Read a list of rows in dict or list form from a csv. The headers argument is either a row number or list of row numbers (in case of multi- line headers) to be considered as headers (rows start counting at 1), or the actual headers defined as a list of strings. If not set, all rows will be treated as containing values.
write_list_to_csv — Write a list of rows in dict or list form to a csv. (The headers argument is either a row number (rows start counting at 1), or the actual headers defined as a list of strings. If not set, all rows will be treated as containing values.)
args_to_dict — Convert command line arguments in a comma separated string to a dictionary.

invert_dictionary(d: MutableMapping) → dict

Invert a dictionary from key - value to value - key. Assumes one to one mapping between keys and values.

Parameters

d : MutableMapping — Dictionary

Returns

dict — Return inverse of dictionary

merge_two_dictionaries(a: MutableMapping, b: MutableMapping, merge_lists: bool = False) → MutableMapping

Merges b into a and returns merged result.

NOTE: tuples and arbitrary objects are not handled as it is totally ambiguous what should happen

Parameters

a : MutableMapping — dictionary to merge into
b : MutableMapping — dictionary to merge from
merge_lists : bool — Whether to merge lists (True) or replace lists (False). Default is False.

Returns

MutableMapping — Merged dictionary

Raises

ValueError

merge_dictionaries(dicts: Sequence[MutableMapping], merge_lists: bool = False) → MutableMapping

Merges all dictionaries in dicts into a single dictionary and returns result.

Parameters

dicts : Sequence[MutableMapping] — Dictionaries to merge into the first one in the list
merge_lists : bool — Whether to merge lists (True) or replace lists (False). Default is False.

Returns

MutableMapping — Merged dictionary

dict_diff(d1: MutableMapping, d2: MutableMapping, no_key: str = '') → dict

Compares two dictionaries.

Parameters

d1 : MutableMapping — First dictionary to compare
d2 : MutableMapping — Second dictionary to compare
no_key : str — What value to use if key is not found Defaults to ''.

Returns

dict — Comparison dictionary

dict_of_lists_add(dictionary: MutableMapping, key: Any, value: Any) → None

Add value to a list in a dictionary by key.

Parameters

dictionary : MutableMapping — Dictionary to which to add values
key : Any — Key within dictionary
value : Any — Value to add to list in dictionary

Returns

None — None

dict_of_sets_add(dictionary: MutableMapping, key: Any, value: Any) → None

Add value to a set in a dictionary by key.

Parameters

dictionary : MutableMapping — Dictionary to which to add values
key : Any — Key within dictionary
value : Any — Value to add to set in dictionary

Returns

None — None

dict_of_dicts_add(dictionary: MutableMapping, parent_key: Any, key: Any, value: Any) → None

Add key value pair to a dictionary within a dictionary by key.

Parameters

dictionary : MutableMapping — Dictionary to which to add values
parent_key : Any — Key within parent dictionary
key : Any — Key within dictionary
value : Any — Value to add to set in dictionary

Returns

None — None

list_distribute_contents_simple(input_list: Sequence, function: Callable[[Any], Any] = lambda x: x) → list

Distribute the contents of a list eg. [1, 1, 1, 2, 2, 3] -> [1, 2, 3, 1, 2, 1]. List can contain complex types like dictionaries in which case the function can return the appropriate value eg. lambda x: x[KEY]

Parameters

input_list : Sequence — List to distribute values
function : Callable[[Any], Any] — Return value to use for distributing. Defaults to lambda x: x.

Returns

list — Distributed list

list_distribute_contents(input_list: Sequence, function: Callable[[Any], Any] = lambda x: x) → list

Distribute the contents of a list eg. [1, 1, 1, 2, 2, 3] -> [1, 2, 1, 2, 1, 3]. List can contain complex types like dictionaries in which case the function can return the appropriate value eg. lambda x: x[KEY]

Parameters

input_list : Sequence — List to distribute values
function : Callable[[Any], Any] — Return value to use for distributing. Defaults to lambda x: x.

Returns

list — Distributed list

extract_list_from_list_of_dict(list_of_dict: Sequence[dict], key: Any) → list

Extract a list by looking up key in each member of a list of dictionaries.

Parameters

list_of_dict : Sequence[dict] — List of dictionaries
key : Any — Key to find in each dictionary

Returns

list — List containing values returned from each dictionary

key_value_convert(dictin: MutableMapping, keyfn: Callable[[Any], Any] = lambda x: x, valuefn: Callable[[Any], Any] = lambda x: x, dropfailedkeys: bool = False, dropfailedvalues: bool = False, exception: Exception = ValueError) → dict

Convert keys and/or values of dictionary using functions passed in as parameters.

Parameters

dictin : MutableMapping — Input dictionary
keyfn : Callable[[Any], Any] — Function to convert keys. Defaults to lambda x: x
valuefn : Callable[[Any], Any] — Function to convert values. Defaults to lambda x: x
dropfailedkeys : bool — Whether to drop dictionary entries where key conversion fails. Defaults to False.
dropfailedvalues : bool — Whether to drop dictionary entries where value conversion fails. Defaults to False.
exception : Exception — The exception to expect if keyfn or valuefn fail. Defaults to ValueError.

Returns

dict — New dictionary with converted keys and/or values

integer_key_convert(dictin: MutableMapping, dropfailedkeys: bool = False) → dict

Convert keys of dictionary to integers.

Parameters

dictin : MutableMapping — Input dictionary
dropfailedkeys : bool — Whether to drop dictionary entries where key conversion fails. Defaults to False.

Returns

dict — Dictionary with keys converted to integers

integer_value_convert(dictin: MutableMapping, dropfailedvalues: bool = False) → dict

Convert values of dictionary to integers.

Parameters

dictin : MutableMapping — Input dictionary
dropfailedvalues : bool — Whether to drop dictionary entries where key conversion fails. Defaults to False.

Returns

dict — Dictionary with values converted to integers

float_value_convert(dictin: MutableMapping, dropfailedvalues: bool = False) → dict

Convert values of dictionary to floats.

Parameters

dictin : MutableMapping — Input dictionary
dropfailedvalues : bool — Whether to drop dictionary entries where key conversion fails. Defaults to False.

Returns

dict — Dictionary with values converted to floats

avg_dicts(dictin1: MutableMapping, dictin2: MutableMapping, dropmissing: bool = True) → dict

Create a new dictionary from two dictionaries by averaging values.

Parameters

dictin1 : MutableMapping — First input dictionary
dictin2 : MutableMapping — Second input dictionary
dropmissing : bool — Whether to drop keys missing in one dictionary. Defaults to True.

Returns

dict — Dictionary with values being average of 2 input dictionaries

Read a list of rows in dict or list form from a csv. The headers argument is either a row number or list of row numbers (in case of multi- line headers) to be considered as headers (rows start counting at 1), or the actual headers defined as a list of strings. If not set, all rows will be treated as containing values.

Parameters

url : Path | str — URL or path to read from
headers : int | Sequence[int] | Sequence[str] | None — Row number of headers. Defaults to None.
dict_form : bool — Return dict (requires headers parameter) or list for each row. Defaults to False (list)
**kwargs : Any — Other arguments to pass to Tabulator Stream

Returns

list[list | dict] — List of rows in dict or list form

Raises

ValueError

Write a list of rows in dict or list form to a csv. (The headers argument is either a row number (rows start counting at 1), or the actual headers defined as a list of strings. If not set, all rows will be treated as containing values.)

Parameters

filepath : Path | str — Path to write to
rows : list[Sequence | Mapping] — List of rows in dict or list form
headers : int | Sequence[str] | None — Headers to write. Defaults to None.
columns : Sequence[int] | Sequence[str] | None — Columns to write. Defaults to all.
encoding : str | None — Encoding to use. Defaults to None (infer encoding).

Returns

None — None

args_to_dict(args: str) → dict

Convert command line arguments in a comma separated string to a dictionary.

Parameters

args : str — Command line arguments

Returns

dict — Dictionary of arguments