InfiniteIterable

class iteration_utilities.InfiniteIterable(iterable)

Like Iterable but indicates that the wrapped iterable is infinitly long.

Warning

The Iterable.as_* methods are not available for InfiniteIterable because it would be impossible to create these types. Use InfiniteIterable.islice() or InfiniteIterable.takewhile() to convert an infinite iterable to a finite iterable. It is still possible to iterate over the iterable with for item in ... or using the Python constructors like list directly. This may fail fatally!

Mostly it is not necessary to use InfiniteIterable directly because the corresponding methods on Iterable return an InfiniteIterable when appropriate. However using isinstance(some_iterable, InfiniteIterable) could be used to determine if the Iterable is infinite!

Available methods:

Method Reference
accumulate() See accumulate().
clamp() See clamp().
combinations() See itertools.combinations().
combinations_with_replacement() See itertools.combinations_with_replacement().
compress() See itertools.compress().
cycle() See itertools.cycle().
deepflatten() See deepflatten().
dropwhile() See itertools.dropwhile().
duplicates() See duplicates().
enumerate() See enumerate().
filter() See filter().
filterfalse() See itertools.filterfalse().
flatten() See flatten().
from_applyfunc() See applyfunc().
from_count() See itertools.count().
from_iterfunc_exception() See iter_except().
from_iterfunc_sentinel() See iter().
from_itersubclasses() See itersubclasses().
from_repeat() See itertools.repeat().
from_repeatfunc() See repeatfunc().
from_tabulate() See tabulate().
getitem() See getitem()
grouper() See grouper().
insert() See insert()
intersperse() See intersperse().
islice() See itertools.islice().
map() See map().
ncycles() See ncycles().
pad() See pad().
permutations() See itertools.permutations().
powerset() See powerset().
remove() See remove().
replace() See replace().
replicate() See replicate().
split() See split().
starfilter() See starfilter().
starmap() See itertools.starmap().
successive() See successive().
tail() See tail().
takewhile() See itertools.takewhile().
unique_everseen() See unique_everseen().
unique_justseen() See unique_justseen().
__getitem__(idx)

See getitem(). If the idx is a slice then it is appropriatly converted for the getitem() call.

accumulate(func=<default>, start=<default>)

See accumulate().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).accumulate().as_list()
[1, 3, 6, 10, 15, 21, 28, 36, 45]
>>> from operator import mul
>>> Iterable(range(1, 10)).accumulate(mul, 2).as_list()
[2, 4, 12, 48, 240, 1440, 10080, 80640, 725760]
>>> Iterable(range(1, 10)).accumulate(func=mul, start=3).as_list()
[3, 6, 18, 72, 360, 2160, 15120, 120960, 1088640]
clamp(low=<default>, high=<default>, inclusive=<default>, remove=<default>)

See clamp().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).clamp(2, 7, True).as_list()
[3, 4, 5, 6]
>>> Iterable(range(10)).clamp(low=2, high=7, inclusive=True).as_list()
[3, 4, 5, 6]
>>> Iterable(range(10)).clamp(low=2, high=7, remove=False).as_list()
[2, 2, 2, 3, 4, 5, 6, 7, 7, 7]
combinations(r)

See itertools.combinations().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 4)).combinations(2).as_list()
[(1, 2), (1, 3), (2, 3)]
>>> Iterable(range(1, 4)).combinations(r=2).as_list()
[(1, 2), (1, 3), (2, 3)]
combinations_with_replacement(r)

See itertools.combinations_with_replacement().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 4)).combinations_with_replacement(2).as_list()
[(1, 1), (1, 2), (1, 3), (2, 2), (2, 3), (3, 3)]
>>> Iterable(range(1, 4)).combinations_with_replacement(r=2).as_list()
[(1, 1), (1, 2), (1, 3), (2, 2), (2, 3), (3, 3)]
compress(selectors)

See itertools.compress().

Examples

>>> from iteration_utilities import Iterable
>>> sel = [0, 1, 0, 1, 0, 1, 1, 1, 0]
>>> Iterable(range(1, 10)).compress(sel).as_list()
[2, 4, 6, 7, 8]
>>> Iterable(range(1, 10)).compress(selectors=sel).as_list()
[2, 4, 6, 7, 8]
cycle()

See itertools.cycle().

Examples

>>> from iteration_utilities import Iterable
>>> it = Iterable([1, 2]).cycle()
>>> for item in it.islice(5):
...     print(item)
1
2
1
2
1
deepflatten(depth=<default>, types=<default>, ignore=<default>)

See deepflatten().

Examples

>>> from iteration_utilities import Iterable
>>> lst = [1, 2, 3, [1, 2, 3, [1, 2, 3]]]
>>> Iterable(lst).deepflatten().as_list()
[1, 2, 3, 1, 2, 3, 1, 2, 3]
>>> Iterable(lst).deepflatten(1, list, str).as_list()
[1, 2, 3, 1, 2, 3, [1, 2, 3]]
>>> Iterable(lst).deepflatten(depth=1,
...                           types=list, ignore=str).as_list()
[1, 2, 3, 1, 2, 3, [1, 2, 3]]
dropwhile(predicate)

See itertools.dropwhile().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).dropwhile(lambda x: x < 5).as_list()
[5, 6, 7, 8, 9]
>>> Iterable(range(1, 10)).dropwhile(
...     predicate=lambda x: x < 3).as_list()
[3, 4, 5, 6, 7, 8, 9]
duplicates(key=<default>)

See duplicates().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1, 1, 2, 1]).duplicates().as_list()
[1, 1]
>>> Iterable([1, -1, 2, 1]).duplicates(abs).as_list()
[-1, 1]
>>> Iterable([1, -1, 2, 1]).duplicates(key=abs).as_list()
[-1, 1]
enumerate(start=<default>)

See enumerate().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 8)).enumerate().as_list()
[(0, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7)]
>>> Iterable(range(1, 8)).enumerate(4).as_list()
[(4, 1), (5, 2), (6, 3), (7, 4), (8, 5), (9, 6), (10, 7)]
>>> Iterable(range(1, 8)).enumerate(start=2).as_list()
[(2, 1), (3, 2), (4, 3), (5, 4), (6, 5), (7, 6), (8, 7)]
filter(function)

See filter().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).filter(None).as_list()
[1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> from iteration_utilities import is_even
>>> Iterable(range(1, 10)).filter(is_even).as_list()
[2, 4, 6, 8]
>>> Iterable(range(1, 10)).filter(function=is_even).as_list()
[2, 4, 6, 8]
filterfalse(predicate)

See itertools.filterfalse().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).filterfalse(None).as_list()
[]
>>> from iteration_utilities import is_odd
>>> Iterable(range(1, 10)).filterfalse(is_odd).as_list()
[2, 4, 6, 8]
>>> Iterable(range(1, 10)).filterfalse(predicate=is_odd).as_list()
[2, 4, 6, 8]
flatten()

See flatten().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([(1, 2, 3), [3, 2, 1]]).flatten().as_list()
[1, 2, 3, 3, 2, 1]
from_applyfunc(func, initial)

See applyfunc().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable.from_applyfunc(lambda x: x*2, 10).islice(5).as_list()
[20, 40, 80, 160, 320]
>>> Iterable.from_applyfunc(func=lambda x: x*2,
...                         initial=10).islice(5).as_list()
[20, 40, 80, 160, 320]

Warning

This returns an InfiniteIterable.

from_count(start=<default>, step=<default>)

See itertools.count().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable.from_count().islice(10).as_list()
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> Iterable.from_count(4, 3).islice(10).as_list()
[4, 7, 10, 13, 16, 19, 22, 25, 28, 31]
>>> Iterable.from_count(start=4, step=3).islice(10).as_list()
[4, 7, 10, 13, 16, 19, 22, 25, 28, 31]

Warning

This returns an InfiniteIterable.

from_iterfunc_exception(func, exception, first=<default>)

See iter_except().

Examples

>>> from iteration_utilities import Iterable
>>> class Func:
...     def __init__(self):
...         self.val = 0
...     def setlim(self, val=3):
...         self.val = val
...         return 'init'
...     def __call__(self):
...         self.val += 1
...         if self.val < 8:
...             return 3
...         raise ValueError()
>>> Iterable.from_iterfunc_exception(Func(), ValueError).as_list()
[3, 3, 3, 3, 3, 3, 3]
>>> f = Func()
>>> Iterable.from_iterfunc_exception(f, ValueError, f.setlim).as_list()
['init', 3, 3, 3, 3]
from_iterfunc_sentinel(func, sentinel)

See iter().

Examples

>>> from iteration_utilities import Iterable
>>> class Func:
...     def __init__(self):
...         self.val = 0
...     def __call__(self):
...         self.val += 1
...         return 4 if self.val < 8 else 10
>>> Iterable.from_iterfunc_sentinel(Func(), 10).as_list()
[4, 4, 4, 4, 4, 4, 4]
from_itersubclasses(object)

See itersubclasses().

Examples

>>> from iteration_utilities import Iterable
>>> class A(object): pass
>>> class B(A): pass
>>> class C(A): pass
>>> class D(C): pass
>>> Iterable.from_itersubclasses(A).as_list()
[<class 'iteration_utilities._classes.B'>, <class 'iteration_utilities._classes.C'>, <class 'iteration_utilities._classes.D'>]
>>> Iterable.from_itersubclasses(C).as_list()
[<class 'iteration_utilities._classes.D'>]
from_repeat(object, times=<default>)

See itertools.repeat().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable.from_repeat(5).islice(10).as_list()
[5, 5, 5, 5, 5, 5, 5, 5, 5, 5]
>>> Iterable.from_repeat(5, 5).as_list()
[5, 5, 5, 5, 5]
>>> Iterable.from_repeat(object=5, times=5).as_list()
[5, 5, 5, 5, 5]

Warning

This returns an InfiniteIterable if times is not given.

from_repeatfunc(func, *args, **times)

See repeatfunc().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable.from_repeatfunc(int).islice(10).as_list()
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
>>> Iterable.from_repeatfunc(int, times=10).as_list()
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
>>> import random  
>>> # Something more useful: Creating 10 random integer
>>> Iterable.from_repeatfunc(random.randint, 0, 5,
...                          times=10).as_list()  
[1, 3, 1, 3, 5, 2, 4, 1, 0, 1]

Warning

This returns an InfiniteIterable if times is not given.

from_tabulate(func, start=<default>)

See tabulate().

Examples

>>> from iteration_utilities import Iterable, chained
>>> roundint = chained(round, int)
>>> import operator
>>> Iterable.from_tabulate(operator.neg).islice(8).as_list()
[0, -1, -2, -3, -4, -5, -6, -7]
>>> from math import gamma
>>> Iterable.from_tabulate(gamma, 1).islice(8).map(roundint).as_tuple()
(1, 1, 2, 6, 24, 120, 720, 5040)
>>> Iterable.from_tabulate(func=gamma, start=2).islice(7).map(roundint).as_tuple()
(1, 2, 6, 24, 120, 720, 5040)

Warning

This returns an InfiniteIterable.

getitem(item)

See getitem()

Parameters:

item : int or slice

The item or items to retrieve

Returns:

parts : any type or generator

If item was an integer the return is a singly item otherwise it returns a generator of the items.

Examples

With integers:

>>> from iteration_utilities import Iterable
>>> it = Iterable(range(10))
>>> it[2]
2

>>> it[-1]  # -1 is the **only** allowed negative integer.
9

With a tuple of integer (they will be sorted internally!):

>>> Iterable(range(100))[-1, 8, 3, 10, 46]  # -1 indicates last
[3, 8, 10, 46, 99]

>>> Iterable(range(100))[3, 8, 10, 46]
[3, 8, 10, 46]

With slices:

>>> it[1:].as_list()
[1, 2, 3, 4, 5, 6, 7, 8, 9]

>>> it[1:8:2].as_list()
[1, 3, 5, 7]

Slices with negative values (only these cases are possible!):

>>> # start and stop negative; step None
>>> it[-5:-2].as_list()
[5, 6, 7]

>>> # start and stop negative; step positive
>>> it[-6:-1:2].as_list()
[4, 6, 8]

>>> # start negative, stop and step None
>>> it[-6:].as_list()
[4, 5, 6, 7, 8, 9]

>>> # start negative, stop None, step positive
>>> it[-6::2].as_list()
[4, 6, 8]

It’s also possible to use getitem method directly, but you have to pass in the appropriate value(s) or slice:

>>> Iterable(range(10)).getitem(3)
3

>>> Iterable(range(10)).getitem(slice(5, 8)).as_tuple()
(5, 6, 7)

Note

This function might also turn an InfiniteIterable into an Iterable if the slice has a positive stop.

>>> Iterable.from_count()[:4]  
<Iterable: <itertools.islice object at ...>>
grouper(n, fillvalue=<default>, truncate=<default>)

See grouper().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).grouper(2).as_list()
[(1, 2), (3, 4), (5, 6), (7, 8), (9,)]
>>> Iterable(range(1, 10)).grouper(2, None).as_list()
[(1, 2), (3, 4), (5, 6), (7, 8), (9, None)]
>>> Iterable(range(1, 10)).grouper(n=2, fillvalue=None).as_list()
[(1, 2), (3, 4), (5, 6), (7, 8), (9, None)]
>>> Iterable(range(1, 10)).grouper(n=2, truncate=True).as_list()
[(1, 2), (3, 4), (5, 6), (7, 8)]
insert(element, idx, unpack=<default>)

See insert()

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).insert(100, 2).as_list()
[0, 1, 100, 2, 3, 4, 5, 6, 7, 8, 9]

Warning

This returns an InfiniteIterable if unpack=True and the element is an InfiniteIterable.

>>> Iterable(range(10)).insert(Iterable.from_count(), 3, unpack=True) 
<InfiniteIterable: <itertools.chain object at ...>>
intersperse(e)

See intersperse().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).intersperse(0).as_list()
[1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6, 0, 7, 0, 8, 0, 9]
>>> Iterable(range(1, 10)).intersperse(e=0).as_list()
[1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6, 0, 7, 0, 8, 0, 9]
islice(*args)

See itertools.islice().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).islice(2).as_list()
[1, 2]
>>> Iterable(range(1, 10)).islice(2, 6).as_list()
[3, 4, 5, 6]
>>> Iterable(range(1, 10)).islice(2, 6, 2).as_list()
[3, 5]

Note

This method converts an InfiniteIterable to a normal Iterable if a stop is given.

map(function)

See map().

Examples

>>> from iteration_utilities import Iterable, square
>>> Iterable(range(1, 10)).map(square).as_list()
[1, 4, 9, 16, 25, 36, 49, 64, 81]
>>> Iterable(range(1, 10)).map(function=square).as_list()
[1, 4, 9, 16, 25, 36, 49, 64, 81]
ncycles(n)

See ncycles().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 4)).ncycles(3).as_list()
[1, 2, 3, 1, 2, 3, 1, 2, 3]
>>> Iterable(range(1, 4)).ncycles(n=3).as_list()
[1, 2, 3, 1, 2, 3, 1, 2, 3]
pad(fillvalue=<default>, nlead=<default>, ntail=<default>)

See pad().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([2]).pad(None, ntail=None).islice(10).as_list()
[2, None, None, None, None, None, None, None, None, None]
>>> Iterable([2]).pad(nlead=9).as_list()
[None, None, None, None, None, None, None, None, None, 2]
>>> Iterable([2]).pad(0, ntail=9).as_list()
[2, 0, 0, 0, 0, 0, 0, 0, 0, 0]
>>> Iterable([2]).pad(0, 1, 2).as_list()
[0, 2, 0, 0]

Warning

This returns an InfiniteIterable if ntail=None.

permutations(r=<default>)

See itertools.permutations().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 4)).permutations().as_list()
[(1, 2, 3), (1, 3, 2), (2, 1, 3), (2, 3, 1), (3, 1, 2), (3, 2, 1)]
>>> Iterable(range(1, 4)).permutations(2).as_list()
[(1, 2), (1, 3), (2, 1), (2, 3), (3, 1), (3, 2)]
>>> Iterable(range(1, 4)).permutations(r=2).as_list()
[(1, 2), (1, 3), (2, 1), (2, 3), (3, 1), (3, 2)]
powerset()

See powerset().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 4)).powerset().as_list()
[(), (1,), (2,), (3,), (1, 2), (1, 3), (2, 3), (1, 2, 3)]
remove(idx=<default>, start=<default>, stop=<default>)

See remove().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).remove(idx=2).as_list()
[0, 1, 3, 4, 5, 6, 7, 8, 9]

Note

This function might also turn an InfiniteIterable into an Iterable if idx and stop are None.

>>> Iterable.from_count().remove(start=4)  
<Iterable: <itertools.islice object at ...>>
replace(element, idx=<default>, start=<default>, stop=<default>, unpack=<default>)

See replace().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).replace(10, idx=2).as_list()
[0, 1, 10, 3, 4, 5, 6, 7, 8, 9]

Warning

This returns an InfiniteIterable if unpack=True and the element is an InfiniteIterable.

>>> Iterable(range(10)).replace(Iterable.from_count(), 4, unpack=True)
<InfiniteIterable: <itertools.chain object at ...>>

Note

But this function might also turn an InfiniteIterable into an Iterable if idx and stop are None.

>>> Iterable.from_count().replace(10, start=4)  
<Iterable: <itertools.chain object at ...>>
replicate(times)

See replicate().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 4)).replicate(3).as_list()
[1, 1, 1, 2, 2, 2, 3, 3, 3]
>>> Iterable(range(1, 4)).replicate(times=4).as_list()
[1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3]
split(key, maxsplit=<default>, keep=<default>, keep_before=<default>, keep_after=<default>, eq=<default>)

See split().

Examples

>>> from iteration_utilities import Iterable, is_even
>>> Iterable(range(1, 10)).split(is_even).as_list()
[[1], [3], [5], [7], [9]]
>>> Iterable(range(1, 10)).split(is_even, 2).as_list()
[[1], [3], [5, 6, 7, 8, 9]]
>>> Iterable(range(1, 10)).split(3, 1, True, False, False, True).as_list()
[[1, 2], [3], [4, 5, 6, 7, 8, 9]]
>>> Iterable(range(1, 10)).split(3, 1, False, True, False, True).as_list()
[[1, 2, 3], [4, 5, 6, 7, 8, 9]]
>>> Iterable(range(1, 10)).split(3, 1, False, False, True, True).as_list()
[[1, 2], [3, 4, 5, 6, 7, 8, 9]]
>>> Iterable(range(1, 10)).split(key=2, maxsplit=1,
...                              keep=True, eq=True).as_list()
[[1], [2], [3, 4, 5, 6, 7, 8, 9]]
starfilter(pred)

See iteration_utilities.starfilter().

Examples

>>> from iteration_utilities import Iterable
>>> from operator import eq
>>> Iterable([1] * 20).enumerate().starfilter(eq).as_list()
[(1, 1)]
starmap(function)

See itertools.starmap().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).enumerate().starmap(pow).as_list()
[0, 1, 8, 81, 1024, 15625, 279936, 5764801, 134217728]
successive(times)

See successive().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).successive(2).as_list()
[(1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7), (7, 8), (8, 9)]
>>> Iterable(range(1, 10)).successive(times=2).as_list()
[(1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7), (7, 8), (8, 9)]
tail(n)

See tail().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).tail(2).as_list()
[8, 9]
>>> Iterable(range(1, 10)).tail(n=3).as_list()
[7, 8, 9]
takewhile(predicate)

See itertools.takewhile().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).takewhile(lambda x: x < 4).as_list()
[1, 2, 3]
>>> Iterable(range(1, 10)).takewhile(
...     predicate=lambda x: x < 5).as_list()
[1, 2, 3, 4]

Warning

This method converts an InfiniteIterable to a normal Iterable.

unique_everseen(key=<default>)

See unique_everseen().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(1, 10)).unique_everseen().as_list()
[1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> Iterable(range(1, 10)).unique_everseen(lambda x: x // 3).as_list()
[1, 3, 6, 9]
>>> from iteration_utilities import is_even
>>> Iterable(range(1, 10)).unique_everseen(key=is_even).as_list()
[1, 2]
unique_justseen(key=<default>)

See unique_justseen().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable('aaAAbbBcCcddDDDEEEee').unique_justseen().as_list()
['a', 'A', 'b', 'B', 'c', 'C', 'c', 'd', 'D', 'E', 'e']
>>> from operator import methodcaller
>>> Iterable('aaAAbbBcCcddDDDEEEee').unique_justseen(
...     methodcaller('upper')).as_list()
['a', 'b', 'c', 'd', 'E']
>>> Iterable('aaAAbbBcCcddDDDEEEee').unique_justseen(
...     key=methodcaller('lower')).as_list()
['a', 'b', 'c', 'd', 'E']