Iterable

class iteration_utilities.Iterable(iterable)

A convenience class that allows chaining the iteration_utilities functions.

Parameters:

iterableiterable

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()).

Available methods:

Method	Reference
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_empty()	See empty().
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_fmean()	See statistics.fmean(). (Python >= 3.8)
get_fsum()	See math.fsum().
get_geometric_mean()	See statistics.geometric_mean(). (Python >= 3.8)
get_groupedby()	See groupedby().
get_harmonic_mean()	See statistics.harmonic_mean().
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_multimode()	See statistics.multimode(). (Python >= 3.8)
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_quantiles()	See statistics.quantiles(). (Python >= 3.8)
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().

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'>

Iterable is because allows chaining of several 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 on the iterable 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

Some methods (Iterable.cycle()) create an InfiniteIterable:

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

As well as 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 the class to be aware if the iterable is infinitely long or not and prevent accidental infinite loops. 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 available for InfiniteIterable!

__getitem__(idx)

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

__length_hint__()

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

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:

clstype

Convert the content of Iterable to this class.

Returns:

iterablecls

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, 'c': 3, 'a': 3, 'l': 3, 'u': 2, 'p': 2, 'e': 2, 'r': 2, 'o': 2, 'f': 1, 'g': 1, 't': 1, 'x': 1, 'd': 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:

seperatorstr, optional

The separator 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]

static 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.

static 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.

static from_empty()

Creates an empty Iterable.

Added in version 0.11.0.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable.from_empty().as_list()
[]

static 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]

static 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]

static from_itersubclasses(object)

See itersubclasses().

Examples

>>> from iteration_utilities import Iterable

>>> class A: 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'>]

static from_maybe_iterable(obj, excluded_types=<default>, empty_if_none=<default>)

See always_iterable().

Added in version 0.11.0.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable.from_maybe_iterable([1, 2, 3]).as_list()
[1, 2, 3]

>>> Iterable.from_maybe_iterable(1).as_list()
[1]

>>> Iterable.from_maybe_iterable([1, 2, 3], excluded_types=list).as_list()
[[1, 2, 3]]

>>> Iterable.from_maybe_iterable(None, empty_if_none=True).as_list()
[]

static 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.

static 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.

static 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_fmean()

See statistics.fmean().

Note

Python >= 3.8 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_fmean()
4.230769...

get_fsum()

See math.fsum().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_fsum()
45.0

get_geometric_mean()

See statistics.geometric_mean().

Note

Python >= 3.8 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_geometric_mean()
3.250146...

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_harmonic_mean()

See statistics.harmonic_mean().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1,1,1,2,2,3,4,5,6,7,7,8,8]).get_harmonic_mean()
2.369791...

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().

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().

Examples

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

get_median()

See statistics.median().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(11)).get_median()
5

get_median_grouped(interval=<default>)

See statistics.median_grouped().

Examples

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

get_median_high()

See statistics.median_high().

Examples

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

get_median_low()

See statistics.median_low().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable(range(10)).get_median_low()
4

get_min(key=<default>, default=<default>)

See min().

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().

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1,1,1,2,2,3,4,5,6,7,7,8,8]).get_mode()
1

get_multimode()

See statistics.multimode().

Note

Python >= 3.8 is required for this function.

Examples

>>> from iteration_utilities import Iterable
>>> Iterable([1,1,1,2,2,2,3,4,5,6,7,7,8,8]).get_multimode()
[1, 2]

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().

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().

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_quantiles(n=<default>, method=<default>)

See statistics.quantiles().

Note

Python >= 3.8 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_quantiles()
[1.5, 4.0, 7.0]
>>> Iterable([1,1,1,2,2,3,4,5,6,7,7,8,8]).get_quantiles(n=10)
[1.0, 1.0, 2.0, 2.6, 4.0, 5.4, 6.8, 7.2, 8.0]
>>> Iterable([1,1,1,2,2,3,4,5,6,7,7,8,8]).get_quantiles(n=10, method='inclusive')
[1.0, 1.4, 2.0, 2.8, 4.0, 5.2, 6.4, 7.0, 7.8]

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().

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().

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:

itemint or slice

The item or items to retrieve

Returns:

partsany 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]

>>> Iterable([1, 2, 3, 4]).islice(1, None).as_list()
[2, 3, 4]

>>> Iterable([1, 2, 3, 4]).islice(None).as_list()
[1, 2, 3, 4]

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
>>> 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']