groupedby

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

Group values of iterable by a key function as dictionary.

Parameters:
iterableiterable

The iterable to group by a key function.

keycallable

The items of the iterable are grouped by the key(item).

keepcallable, optional

If given append only the result of keep(item) instead of item.

reducecallable, 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().

reducestartany type, optional

If given (even as None) it will be interpreted as start value for the reduce function.

Note

Can only be specified if reduce is given.

Returns:
groupeddict

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.groupby() 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 start value:

>>> 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