sprig.iterutils module

Some utility functions for working with iterators.

sprig.iterutils.bucket_merge(iterable: Iterable[T], sort_key: Callable[[T], Any], bucket_key: Callable[[T], U], buckets: Iterable[U]) → Iterator[T]

Sort a partially sorted iterable lazily

If the iterable can be split into individually sorted buckets then this function will sort it.

sprig.iterutils.imerge(iterables: Iterable[Iterable[T]], key: Callable[[T], Any] = <function <lambda>>) → Iterator[T]

Merge individually sorted iterables to a single sorted iterator.

This is similar to the merge step in merge-sort except

• it handles an arbitrary number of iterators, and

• eagerly consumes only one item from each iterator.

If the laziness is not needed, it is probably better to concatenate and sort.

Sorted normally

>>> list(imerge([[1, 4], [2, 3]]))
[1, 2, 3, 4]

Key changes order (Note that the sorted order of inputs is different)s

>>> list(imerge([[4, 1], [2, 3]], key=lambda x: (x%2, x)))
[2, 4, 1, 3]

sprig.iterutils.split(iterable: Iterable[T], edges: Iterable[U], cmp: Optional[Callable[[T, U], bool]] = None) → Iterator[List[T]]

Yield lists of items from iterable grouped by edges

By default this function will insert a split before an item that is equal to an edge but this can be adjusted using cmp.

cmp can also be used if the items in iterable cannot directly be compared to the edges.

The number of lists yielded is guaranteed to be len(edges) + 1.

Note that whereas more_itertools.split_before() will not yield empty buckets, this function will.

>>> list(split([0, 2, 4, 6, 8], [3, 4]))
[[0, 2], [], [4, 6, 8]]

>>> after = lambda item, edge: item <= edge
>>> list(split([0, 2, 4, 6, 8], [3, 4], after))
[[0, 2], [4], [6, 8]]

>>> list(split([2], [1, 3]))
[[], [2], []]

sprig.iterutils.split_annotated(iterable: Iterable[T], edges: Iterable[U], cmp: Optional[Callable[[T, U], bool]] = None) → Iterator[Tuple[Optional[U], Optional[U], List[T]]]

Like split() but annotates the buckets with their edges

>>> list(split_annotated([0, 2, 4, 6, 8], [3, 4]))
[(None, 3, [0, 2]), (3, 4, []), (4, None, [4, 6, 8])]