# groupedby¶

iteration_utilities.groupedby(iterable, key, keep=None, reduce=None, reducestart=None)

Group values of iterable by a key function as dictionary.

Parameters: iterable : iterable The iterable to group by a key function. key : callable The items of the iterable are grouped by the key(item). keep : callable, optional If given append only the result of keep(item) instead of item. reduce : callable, optional If given then instead of returning a list of all items reduce them using the binary reduce function. This works like the func parameter in functools.reduce(). reducestart : any type, optional If given (even as None) it will be interpreted as startvalue for the reduce function. Note Can only be specified if reduce is given. grouped : dict A dictionary where the keys represent the key(item) and the values are lists containing all items having the same key.

Notes

This function differs from itertools.groupy in several ways: (1) This function is eager (consumes the iterable in one go) and (2) the itertools function only groups the iterable locally.

Examples

A simple example:

>>> from iteration_utilities import groupedby
>>> from operator import itemgetter, add
>>> dct = groupedby(['a', 'bac', 'ba', 'ab', 'abc'], key=itemgetter(0))
>>> dct['a']
['a', 'ab', 'abc']
>>> dct['b']
['bac', 'ba']


One could also specify a keep function:

>>> dct = groupedby(['a', 'bac', 'ba', 'ab', 'abc'], key=itemgetter(0), keep=len)
>>> dct['a']
[1, 2, 3]
>>> dct['b']
[3, 2]


Or reduce all values for one key:

>>> from iteration_utilities import is_even
>>> dct = groupedby([1, 2, 3, 4, 5], key=is_even, reduce=add)
>>> dct[True]  # 2 + 4
6
>>> dct[False]  # 1 + 3 + 5
9


using reduce also allows to specify a startvalue:

>>> dct = groupedby([1, 2, 3, 4, 5], key=is_even, reduce=add, reducestart=7)
>>> dct[True]  # 7 + 2 + 4
13
>>> dct[False]  # 7 + 1 + 3 + 5
16