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.

Returns:

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