Iterable

class iteration_utilities.Iterable(iterable)

A convenience class that allows chaining the iteration_utilities functions.

Parameters:

iterable : iterable

Any kind of iterable.

Notes

Warning

If the iterable is infinite you should not create the Iterable instance directly (i.e. Iterable(count()). You could use the Iterable.from_count() or create an InfiniteIterable: InfiniteIterable(count()).

Examples

You can create an instance from any object that implements the iteration protocol. For example the Python types list, tuple, set, frozenset, str, dict, dict.values(), dict.items(), range just to name a few:

>>> from iteration_utilities import Iterable
>>> Iterable([1,2,3,4])
<Iterable: [1, 2, 3, 4]>

>>> Iterable('abcdefghijklmnopqrstuvwxyz')
<Iterable: 'abcdefghijklmnopqrstuvwxyz'>

The primary use of Iterable is because it allows easy chaining of several functional programming functions implemented in Python (map(), filter(), ...), itertools and iteration_utilities:

>>> Iterable([1,2,3,4]).islice(1,3).map(float).as_list()
[2.0, 3.0]

The methods islice() and map() are only evaluated when as_list() is called. The class can also be used in for loops:

>>> from iteration_utilities import is_even
>>> for item in Iterable(range(100, 120)).filter(is_even).accumulate():
...     print(item)
100
202
306
412
520
630
742
856
972
1090

Using some methods (Iterable.cycle()) create an InfiniteIterable:

>>> Iterable(range(10)).cycle()  
<InfiniteIterable: <itertools.cycle object at ...>>

Also some of the staticmethods (from_x):

>>> Iterable.from_count()
<InfiniteIterable: count(0)>

>>> Iterable.from_repeat(10)
<InfiniteIterable: repeat(10)>

>>> Iterable.from_repeat(10, times=2)  # but not always!
<Iterable: repeat(10, 2)>

This logic allows to be aware if the iterable is infinitly long or not. Some methods can also convert an InfiniteIterable to a normal Iterable again:

>>> Iterable.from_count().islice(2, 5)  
<Iterable: <itertools.islice object at ...>>

>>> Iterable.from_count().takewhile(lambda x: x < 100)  
<Iterable: <itertools.takewhile object at ...>>

Iterable implements some constructors for Python types as methods:

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

>>> # But also some less common ones, like OrderedDict
>>> Iterable(range(6)).enumerate(4).as_ordereddict()
OrderedDict([(4, 0), (5, 1), (6, 2), (7, 3), (8, 4), (9, 5)])

Warning

These latter methods are (obviously) not avaiable for InfiniteIterable!

Methods

accumulate() See accumulate().
as_() Convert Iterable to other class.
as_counter() See as_().
as_dict() See as_().
as_frozenset() See as_().
as_list() See as_().
as_ordereddict() See as_().
as_set() See as_().
as_string() Get the iterable as string.
as_tuple() See as_().
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().
get_all() See all().
get_all_distinct() See all_distinct().
get_all_equal() See all_equal().
get_all_monotone() See all_monotone().
get_any() See any().
get_argmax() See argmax().
get_argmin() See argmin().
get_argsorted() See argsorted().
get_count_items() See count_items().
get_first() See nth().
get_fsum() See math.fsum().
get_groupedby() See groupedby().
get_last() See nth().
get_max() See max().
get_mean() See statistics.mean().
get_median() See statistics.median().
get_median_grouped() See statistics.median_grouped().
get_median_high() See statistics.median_high().
get_median_low() See statistics.median_low().
get_min() See min().
get_minmax() See minmax().
get_mode() See statistics.mode().
get_nlargest() See heapq.nlargest().
get_nsmallest() See heapq.nsmallest().
get_nth() See nth().
get_one() See one().
get_partition() See partition().
get_pstdev() See statistics.pstdev().
get_pvariance() See statistics.pvariance().
get_reduce() See functools.reduce().
get_second() See nth().
get_sorted() See sorted().
get_stdev() See statistics.stdev().
get_sum() See sum().
get_third() See nth().
get_variance() See statistics.variance().
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().
reversed() See reversed().
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.

__length_hint__()

Tries to estimate for the length of the instance (returns 0 if an estimation is not possible).

Note

Requires Python >= 3.4

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]
as_(cls)

Convert Iterable to other class.

Parameters:

cls : type

Convert the content of Iterable to this class.

Returns:

iterable : cls

The Iterable as cls.

Notes

Be careful if you use this method because the Iterable may be infinite.

as_counter()

See as_().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable('supercalifragilisticexpialidocious').as_counter()  
Counter({'i': 7, 's': 3, 'l': 3, 'c': 3, 'a': 3, 'e': 2, 'o': 2, 'p': 2, 'r': 2, 'u': 2, 'd': 1, 'g': 1, 'f': 1, 'x': 1, 't': 1})
>>> Iterable([1, 1, 1]).as_counter()
Counter({1: 3})
as_dict()

See as_().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1]).enumerate().as_dict()
{0: 1}
as_frozenset()

See as_().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([5]).as_frozenset()
frozenset({5})
as_list()

See as_().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(5)).as_list()
[0, 1, 2, 3, 4]
as_ordereddict()

See as_().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(3, 6)).enumerate().as_ordereddict()
OrderedDict([(0, 3), (1, 4), (2, 5)])
as_set()

See as_().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1]).as_set()
{1}
as_string(seperator='')

Get the Iterable as string.

Warning

This method does not use as_() and differs from str(Iterable(sth)); It uses str.join().

Parameters:

seperator : str, optional

The seperator between each item from the iterable in the output string.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(5)).as_string()
'01234'
>>> Iterable(range(5)).as_string(' ')
'0 1 2 3 4'
as_tuple()

See as_().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(5)).as_tuple()
(0, 1, 2, 3, 4)
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.

get_all()

See all().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).map(lambda x: x > 2).get_all()
False
>>> Iterable(range(10)).map(lambda x: x >= 0).get_all()
True
get_all_distinct()

See all_distinct().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_all_distinct()
True
>>> Iterable([1, 2, 3, 4, 5, 6, 7, 1]).get_all_distinct()
False
get_all_equal()

See all_equal().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_all_equal()
False
>>> Iterable([1]*100).get_all_equal()
True
get_all_monotone(decreasing=<default>, strict=<default>)

See all_monotone().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_all_monotone()
True
>>> Iterable(range(10)).get_all_monotone(decreasing=False, strict=False)
True
>>> Iterable(range(10)).get_all_monotone(decreasing=True, strict=True)
False
get_any()

See any().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).map(lambda x: x > 2).get_any()
True
>>> Iterable(range(10)).map(lambda x: x >= 10).get_any()
False
get_argmax(key=<default>, default=<default>)

See argmax().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1, 2, -5, 3, 4]).get_argmax()
4
>>> Iterable([1, 2, -5, 3, 4]).get_argmax(abs)
2
>>> Iterable([1, 2, -5, 3, 4]).get_argmax(key=abs)
2
>>> Iterable([]).get_argmax(key=abs, default=-1)
-1
get_argmin(key=<default>, default=<default>)

See argmin().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1, 2, -5, 3, 4]).get_argmin()
2
>>> Iterable([1, 2, -5, 3, 4]).get_argmin(abs)
0
>>> Iterable([1, 2, -5, 3, 4]).get_argmin(key=abs)
0
>>> Iterable([]).get_argmin(key=abs, default=-1)
-1
get_argsorted(key=<default>, reverse=<default>)

See argsorted().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1, 2, -5, 3, 4]).get_argsorted()
[2, 0, 1, 3, 4]
>>> Iterable([1, 2, -5, 3, 4]).get_argsorted(reverse=True)
[4, 3, 1, 0, 2]
>>> Iterable([1, 2, -5, 3, 4]).get_argsorted(key=abs)
[0, 1, 3, 4, 2]
>>> Iterable([1, 2, -5, 3, 4]).get_argsorted(abs, True)
[2, 4, 3, 1, 0]
get_count_items(pred=<default>, eq=<default>)

See count_items().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable((i for i in range(10))).get_count_items()
10
>>> Iterable([1, 2, 3, 2, 1]).get_count_items(2, True)
2
>>> Iterable([1, 2, 3, 2, 1]).get_count_items(pred=2, eq=True)
2
get_first(default=<default>, pred=<default>, truthy=<default>, retpred=<default>, retidx=<default>)

See nth().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_first()
0
>>> Iterable(range(1, 10, 2)).get_first(pred=lambda x: x > 5)
7
get_fsum()

See math.fsum().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_fsum()
45.0
get_groupedby(key, keep=<default>, reduce=<default>, reducestart=<default>)

See groupedby().

Examples

>>> from iteration_utilities import Iterable, is_even
>>> grp = Iterable(range(10)).get_groupedby(is_even)
>>> grp[True]
[0, 2, 4, 6, 8]
>>> grp[False]
[1, 3, 5, 7, 9]
get_last(default=<default>, pred=<default>, truthy=<default>, retpred=<default>, retidx=<default>)

See nth().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_last()
9
>>> Iterable(range(1, 10, 2)).get_last(pred=lambda x: x > 5)
9
get_max(key=<default>, default=<default>)

See max().

Note

The default-parameter is not avaiable at Python 3.3

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1, 2, -5, 3, 4]).get_max()
4
>>> Iterable([1, 2, -5, 3, 4]).get_max(abs)
-5
>>> Iterable([1, 2, -5, 3, 4]).get_max(key=abs)
-5
>>> Iterable([]).get_max(key=abs, default=-1)
-1
get_mean()

See statistics.mean().

Note

Python >= 3.4 is required for this function.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_mean()
4.5
get_median()

See statistics.median().

Note

Python >= 3.4 is required for this function.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(11)).get_median()
5
get_median_grouped(interval=<default>)

See statistics.median_grouped().

Note

Python >= 3.4 is required for this function.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_median_grouped(interval=4)
3.0
get_median_high()

See statistics.median_high().

Note

Python >= 3.4 is required for this function.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_median_high()
5
get_median_low()

See statistics.median_low().

Note

Python >= 3.4 is required for this function.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_median_low()
4
get_min(key=<default>, default=<default>)

See min().

Note

The default-parameter is not avaiable at Python 3.3

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1, 2, -5, 3, 4]).get_min()
-5
>>> Iterable([1, 2, -5, 3, 4]).get_min(abs)
1
>>> Iterable([1, 2, -5, 3, 4]).get_min(key=abs)
1
>>> Iterable([]).get_min(key=abs, default=-1)
-1
get_minmax(key=<default>, default=<default>)

See minmax().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1, 2, -5, 3, 4]).get_minmax()
(-5, 4)
>>> Iterable([1, 2, -5, 3, 4]).get_minmax(abs)
(1, -5)
>>> Iterable([1, 2, -5, 3, 4]).get_minmax(key=abs)
(1, -5)
>>> Iterable([]).get_minmax(key=abs, default=-1)
(-1, -1)
get_mode()

See statistics.mode().

Note

Python >= 3.4 is required for this function.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1,1,1,2,2,3,4,5,6,7,7,8,8]).get_mode()
1
get_nlargest(n, key=<default>)

See heapq.nlargest().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([4,1,2,3,1,5,8,2,-10]).get_nlargest(3)
[8, 5, 4]
>>> Iterable([4,1,2,3,1,5,8,2,-10]).get_nlargest(3, key=abs)
[-10, 8, 5]
get_nsmallest(n, key=<default>)

See heapq.nsmallest().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([4,1,2,3,1,5,8,2]).get_nsmallest(3)
[1, 1, 2]
get_nth(n, default=<default>, pred=<default>, truthy=<default>, retpred=<default>, retidx=<default>)

See nth().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_nth(6)
6
>>> Iterable(range(1, 10, 2)).get_nth(0, pred=lambda x: x > 5)
7
get_one()

See one().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1]).get_one()
1
get_partition(pred=<default>)

See partition().

Examples

>>> from iteration_utilities import Iterable, is_even
>>> Iterable(range(5)).get_partition(is_even)
([1, 3], [0, 2, 4])
get_pstdev(mu=<default>)

See statistics.pstdev().

Note

Python >= 3.4 is required for this function.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1,1,1,2,2,3,4,5,6,7,7,8,8]).get_pstdev()
2.635667953694125
get_pvariance(mu=<default>)

See statistics.pvariance().

Note

Python >= 3.4 is required for this function.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1,1,1,2,2,3,4,5,6,7,7,8,8]).get_pvariance()  
6.94674556...
get_reduce(*args)

See functools.reduce().

Examples

>>> from iteration_utilities import Iterable
>>> from operator import add
>>> Iterable(range(5)).get_reduce(add)
10
get_second(default=<default>, pred=<default>, truthy=<default>, retpred=<default>, retidx=<default>)

See nth().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_second()
1
>>> Iterable(range(1, 10, 2)).get_second(pred=lambda x: x > 5)
9
get_sorted(key=<default>, reverse=<default>)

See sorted().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([3, 1, 5, 12, 7]).get_sorted()
[1, 3, 5, 7, 12]
get_stdev(xbar=<default>)

See statistics.stdev().

Note

Python >= 3.4 is required for this function.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1,1,1,2,2,3,4,5,6,7,7,8,8]).get_stdev()
2.743290182543769
get_sum(start=<default>)

See sum().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([3, 1, 5, 12, 7]).get_sum()
28
>>> Iterable([3, 1, 5, 12, 7]).get_sum(10)
38
get_third(default=<default>, pred=<default>, truthy=<default>, retpred=<default>, retidx=<default>)

See nth().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_third()
2
>>> Iterable(range(1, 10, 2)).get_third(default=-1,
...                                     pred=lambda x: x > 5)
-1
get_variance(mu=<default>)

See statistics.variance().

Note

Python >= 3.4 is required for this function.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1,1,1,2,2,3,4,5,6,7,7,8,8]).get_variance()
7.5256410256410255
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]
reversed()

See reversed().

Warning

This method requires that the wrapped iterable is a Sequence or implements the reversed iterator protocol. Generally this does not work with generators!

Examples

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

See split().

Examples

>>> from iteration_utilities import Iterable, is_even, is_odd
>>> 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']