Iterable, InfiniteIterable and ManyIterables

Warning

Iterable, InfiniteIterable and ManyIterables are currently experimental.

iteration_utilities introduces these three classes that can be used as wrapper for Python iterables. These classes implement the generators present in the Python built-ins, the itertools-module and iteration_utilities as methods.

These can be broadly classified in 4 categories:

Creating an Iterable

The constructor allows wrapping a specified iterable like a list or range object. But it also has several staticmethods for creating an Iterable by other means, these have the prefix from_. For example the iteration_utilities.Iterable.from_repeat() allows to create an Iterable using itertools.repeat().

Modifying and chaining operations

As soon as the Iterable is created one can process it. Each of the normal (not prefixed methods) returns the result of the operation (as generator!) so these can be arbitrarily chained. This allows to chain several operations sequentially.

This can be demonstrated best with an actual example. Suppose we have a list of strings of numbers and we want to convert each letter to an integer and then sum the numbers below 3:

>>> # Python example
>>> from itertools import chain
>>> def less_than_three(x):
...     return x < 3
>>> inp = ['12314253', '12368412612', '7812358', '12381531']
>>> sum(filter(less_than_three, map(int, chain.from_iterable(inp))))
23

>>> # Example with Iterable
>>> from iteration_utilities import Iterable
>>> sum(Iterable(inp).flatten().map(int).filter(less_than_three))
23

Conversion methods

The Iterable implements the iteration protocol so it’s possible to use it everywhere where an iterable is needed. For example with for item in ... or to construct containers, i.e. list(). For convenience (and to prevent some problems with infinite iterables) finite Iterable also have methods to convert them to the desired class. These are prefixed with as_. InfiniteIterable don’t have these to avoid creating an infinitely long list.

Warning

However InfiniteIterable also implement the iteration protocol and could be passed to list, with severe consequences. So use the as_* and get_* methods which will still throw an AttributeError but at least they won’t create an MemoryError or freeze your computer! You have been warned!

Currently folding methods like sum() are implemented with the prefix get_.

Note

See the documentation of Iterable to see which methods are possible or read the next chapters for more background information.

Operating on several iterables

The ManyIterables class implements the methods that operate on several iterables and return a single Iterable or InfiniteIterable.

However it is very important that the iterables given to ManyIterables clearly indicate if they are infinite, otherwise the methods won’t know if the result should be finite or infinite. These infinite iterables should be wrapped in InfiniteIterable or created by the Iterable.from_* methods.