Module functions

dicttools.two_way(dictionary)

Create a new dict containing two-way associations (values to keys and keys to values) from the given dictionary:

>>> two_way({'A': 1, 'B': 2})
{'A': 1, 1: 'A', 2: 'B', 'B': 2}
Parameters:dictionary (dict) – one way association dict
Returns:two way association dict
dicttools.swap(dictionary)

Create a new dict with the given dictionary keys as values and values as keys:

>>> stringify(swap({0: 'A', 1: 'B', 2: 'C'}))
'{A:0, B:1, C:2}'
Parameters:dictionary (dict) – dict to swap
Returns:new swapped dict
dicttools.by(key, *elements)

Create a new dict with the given elements as values, and the keys determined by the given parameter function:

>>> by('real', (1+2j), (2-3j),(-5+0j))
{1.0: (1+2j), 2.0: (2-3j), -5.0: (-5+0j)}

>>> by('imag', [(1+2j), (2-3j),(-5+0j)])
{0.0: (-5+0j), 2.0: (1+2j), -3.0: (2-3j)}

>>> by(lambda x:int(x), "123", "456")
{456: '456', 123: '123'}
Parameters:
  • elements – iterable of elements or elements as varargs
  • key – attribute, by which element could be accessed or lambda function
Returns:

dict with elements, assigned to extracted key
dicttools.group_by(key, *elements)

Create a new dict containing elements grouped by the given key. Returns a dict of list of values, with the same extracted key assigned to this key:

>>> group_by('real', 2j, 0-3j, (-5+0j), (-3+2j), (-5+15j))
{0.0: [2j, -3j], -5.0: [(-5+0j), (-5+15j)], -3.0: [(-3+2j)]}
Parameters:
  • elements – list or tuple of elements
  • key – attribute, by which element could be accessed or lambda function
Returns:

dict with list of elements, assigned to extracted key
dicttools.select(source, *keys)

Create a new dict containing only the selected keys from the source dictionary.

>>> stringify(select({'a': 1, 'b': 2, 'c':4}, 'a', 'c'))
'{a:1, c:4}'
Parameters:
  • source – mapping, from which values are selected
  • keys – keys which should be selected
Returns:

dict with selected values
dicttools.extract(source, *elements, **kwargs)

Create a new dict with attributes name and associated value extracted from object, by keys given as parameter.

Parameters:
  • source – object to extract
  • elements – values which should be extracted
  • key – two arguments function, which extract required argument (default getattr)
Returns:

dict with extracted values
dicttools.merge(*dicts)

Merge the given dicts into a single new dict:

>>> d = merge({'A': 1}, {'B': 2}, {'C': 3})
>>> stringify(d)
'{A:1, B:2, C:3}'

If the same key is found in two or more dicts, the value is taken from last dict containing this key:

>>> d = merge({'A': 1}, {'B': 2}, {'A': 3})
>>> stringify(d)
'{A:3, B:2}'

If the first argument is a function, it is used to merge duplicate values:

>>> d = merge(lambda x,y:x+y, {'A': 1}, {'B': 2}, {'A': 3})
>>> stringify(d)
'{A:4, B:2}'

The returned type is of the same type as the first non-None dict in the list:

>>> d = merge({'A': 1}, {'B': 2}, {'C': 3})
>>> type(d)
<class 'dict'>
>>> from collections import OrderedDict
>>> od = OrderedDict()
>>> od["A"] = 1
>>> d = merge(od, {'B': 2}, {'A': 3})
>>> type(d)
<class 'collections.OrderedDict'>
>>> d = merge(None, od, {'B': 2}, {'A': 3})
>>> type(d)
<class 'collections.OrderedDict'>
Parameters:dicts – dicts to merge
Returns:dict containing all element from given dicts
dicttools.split(dictionary, *conditions, **kwargs)

Split the dictionary to sub-dictionaries based on conditions operated on the keys:

>>> list(split({0: 'A', 1: 'B', 2: 'C', 3: 'D', 4: 'E'}, lambda i: i%3 == 0, lambda i: i%3 == 1))
[{0: 'A', 3: 'D'}, {1: 'B', 4: 'E'}, {2: 'C'}]

When the elements which do not follow any given condition should be omitted, set rest attribute to False:

>>> list(split({0: 'A', 1: 'B', 2: 'C', 3: 'D', 4: 'E'}, lambda i: i%3 == 0, lambda i: i%3 == 1, rest=False))
[{0: 'A', 3: 'D'}, {1: 'B', 4: 'E'}]

When more than one condition is given, each element is included in the first dictionary for which the condition was fulfilled:

>>> list(split({0: 'A', 1: 'B', 2: 'C', 3: 'D', 4: 'E'}, lambda i: i%3 == 0, lambda i: i%2 == 0))
[{0: 'A', 3: 'D'}, {2: 'C', 4: 'E'}, {1: 'B'}]
Parameters:
  • dictionary – elements to split into other sets of elements
  • conditions – functions (name matters): key -> bool or value -> bool or key, value -> bool) which decide that element in current result should be included or not
  • rest – True if should append at end elements which not fulfilled any condition, False otherwise
Returns:

generator for element split according to given condition
dicttools.sift(dictionary, condition, opposite=False)

Select from dictionary only the keys for which the condition is True.

>>> sift({0: 'A', 1: 'B', 2: 'C', 3: 'D', 4: 'E'}, lambda i: i%3 == 0)
{0: 'A', 3: 'D'}

>>> sift({0: 'A', 1: 'B', 2: 'C', 3: 'D', 4: 'E'}, lambda i: i%3 == 0, opposite=True)
{1: 'B', 2: 'C', 4: 'E'}
Parameters:
  • dictionary – set of elements to select subset
  • condition – function (name matters): key -> bool or value -> bool or key, value -> bool) selected remain elements
  • opposite – if True replace “condition” by “not condition” (default False)
Returns:

subset of elements which fulfilled given condition.
dicttools.sift_update(dictionary, condition, opposite=False)

Works like sift, but modifies the given dictionary in place.

Parameters:
  • dictionary – set of elements to select subset
  • condition – function (name matters): key -> bool or value -> bool or key, value -> bool) selected remain elements
  • opposite – if True replace “condition” by “not condition” (default False)
dicttools.contains(sub, super)

Non-recursive. Check if sub dict is included in super dict (both keys and values are equal):

>>> contains({0: 'A', 1: 'B'}, {0: 'A', 1: 'B', 2: 'C'})
True

>>> contains({0: 'A', 1: 'B', 2: 'C'}, {0: 'A', 1: 'B'})
False
Parameters:
  • sub (dict) – the dict, which should be included in super dict
  • super (dict) – the dict, which should include all elements from sub dict
Returns:

true if super contains sub, otherwise false.
dicttools.map_values(function, dictionary)

Transform each value using the given function. Return a new dict with transformed values.

Parameters:
  • function – keys map function
  • dictionary – dictionary to mapping
Returns:

dict with changed values
dicttools.map_keys(function, dictionary)

Transform each key using the given function. Return a new dict with transformed keys.

Parameters:
  • function – values map function
  • dictionary – dictionary to mapping
Returns:

dict with changed (mapped) keys
dicttools.find_key(value, dictionary, default=None)

Find the given value in the given dictionary and returns its key. If value is not found - return default value (None or given). If many elements can be found - return one of them arbitrarily (the first one found):

>>> find_key('d', {'a': 'b', 'c': 'd'})
'c'

>>> find_key('c', {'a': 'b', 'c': 'd'}, default=-1)
-1
Parameters:
  • value – value in dictionary, which for is searching a key
  • dictionary – dictionary to search in
  • default – value returned if value is not in dictionary (default None)
Returns:

key which value in dictionary is assigned to
dicttools.fill_value(keys, value)

Return a dict with the given value assigned to each given key.

>>> fill_value([1, 2, 3], 'a')
{1: 'a', 2: 'a', 3: 'a'}
Parameters:
  • keys – keys, which returned dict should contains
  • value – value, which should be assigned to each key
Returns:

dict with value assigned do each given key
dicttools.stringify(d)

Returns a canonical string representation of the given dict, by sorting its items recursively. This is especially useful in doctests:

>>> stringify({"a":1,"b":2,"c":{"d":3,"e":4}})
'{a:1, b:2, c:{d:3, e:4}}'
dicttools.list_of_values(dictionary, list_of_keys, default=None)

Converts a dict to a list of its values, with the default value inserted for each missing key:

>>> list_of_values({"a":1, "b":2, "d":4}, ["d","c","b","a"])
[4, None, 2, 1]

>>> list_of_values({"a":1, "b":2, "d":4}, ["d","c","b","a"], default=0)
[4, 0, 2, 1]