les_iterables.grouping module

Summary

Classes:

HeadPartitionIterator
PartitionedTail
TailPartitionIterator

Functions:

group_by_terminator	Group the items of of an iterable series, starting a new group after each terminator.
pairwise_padded	Each item in an iterable series with its successor.
partition
partition_tail	Lazily partition an iterable series into a head, and tail of no more than specified length.
split_after_first	Split the iterable after the element matching the predicate.
split_around	Split an iterable series into groups around specific items.

Reference

les_iterables.grouping.partition_tail(items, n)

Lazily partition an iterable series into a head, and tail of no more than specified length.

Parameters:

• items – An iterable series of items.

• n – The maximum number of items to be partitioned into the tail.

Returns:

A pair of iterators, head and tail. Consuming any items from the tail iterator will cause the entire head iterator to be consumed, so typically the head iterator should be consumed before consuming any items from the tail iterator.

Example

To partition the last three items of an iterable series, do:

head, tail = partition_tail(range(10), 3)
for item in head:
    print(item)  # Prints all but the last three

for item in tail:
    print(item)  # Prints the last three

Raises:

ValueError – If n is negative.

class les_iterables.grouping.PartitionedTail(items, n)

Bases: object

class les_iterables.grouping.HeadPartitionIterator(partition_tail)

Bases: object

class les_iterables.grouping.TailPartitionIterator(partition_tail)

Bases: object

les_iterables.grouping.split_around(iterable, predicate, group_factory=None)

Split an iterable series into groups around specific items.

Each item for which the predicate returns True will be in its own group.

Parameters:

• iterable – An iterable series of items to be grouped.

• predicate – A unary callable to detect items which should be placed in their own group.

• group_factory – A callable which creates a group given a sequence of items. By default, a list.

Yields:

A series of groups.

les_iterables.grouping.group_by_terminator(iterable, predicate, group_factory=None)

Group the items of of an iterable series, starting a new group after each terminator.

Each group will have as it’s last item an item from which the predicate returns True. For all preceding items in the group the predicate will return False. The last group yielded may be incomplete, without a terminator.

Parameters:

• iterable – An iterable series of items to be grouped.

• predicate – A unary callable function used to detect group-terminating items from the iterable series.

• group_factory – A callable which creates a group given an sequence of items. By default, a list.

Yields:

A series of groups.

les_iterables.grouping.pairwise_padded(iterable, fillvalue=None)

Each item in an iterable series with its successor.

The number of pairs returned will be equal to the number of items.

Parameters:

• iterable – An iterable series of items to be grouped into pairs.

• fillvalue – The value used as the successor to the last item.

Yields:

A series of 2-tuples contain an item and its successor. For the last item the successor will be the fillvalue.

les_iterables.grouping.split_after_first(iterable, predicate, group_factory=None)

Split the iterable after the element matching the predicate.

Always returns at least 1 group, and no more than 2 groups. If there is no element matching the predicate, the iterable is returned unchanged. If the iterable is empty, returns a single empty group.

Examples

group, *groups = split_after_first([1, 2, 3, 1, 2, 3], lambda x: x == 2))
assert group == [1, 2]
assert groups == [[3, 1, 2, 3]]

group, *groups = split_after_first([1, 2, 3], lambda x: x == 3)
assert group == [1, 2, 3]
assert groups == []

group, *groups = split_after_first('abcde', lambda x: x == 'c')
assert group ==  'abc'
assert groups == ['de']

Returns:

An iterable series of groups.

les_iterables.grouping.partition(iterable, predicate, group_factory=None)