itertools — Functions creating iterators for efficient looping — Python 3.16.0a0 documentation
Navigation index modules | next | previous | Python » 3.16.0a0 Documentation » The Python standard library » Functional Programming Modules » itertools — Functions creating iterators for efficient looping | Theme | itertools — Functions creating iterators for efficient looping ¶ This module implements a number of iterator building blocks inspired by constructs from APL, Haskell, and SML. Each has been recast in a form suitable for Python.
The module standardizes a core set of fast, memory efficient tools that are useful by themselves or in combination. Together, they form an “iterator algebra” making it possible to construct specialized tools succinctly and efficiently in pure Python. For instance, SML provides a tabulation tool: tabulate(f) which produces a sequence f(0), f(1), ... . The same effect can be achieved in Python by combining map() and count() to form map(f, count()) .
General iterators: Iterator Arguments Results Example accumulate() p [,func] p0, p0+p1, p0+p1+p2, … accumulate([1,2,3,4,5]) → 1 3 6 10 15 batched() p, n (p0, p1, …, p_n-1), … batched('ABCDEFG', n=3) → ABC DEF G chain() p, q, … p0, p1, … plast, q0, q1, … chain('ABC', 'DEF') → A B C D E F chain.from_iterable() iterable p0, p1, … plast, q0, q1, … chain.from_iterable(['ABC', 'DEF']) → A B C D E F compress() data, selectors (d[0] if s[0]), (d[1] if s[1]), … compress('ABCDEF', [1,0,1,0,1,1]) → A C E F count() [start[, step]] start, start+step, start+2*step, … count(10) → 10 11 12 13 14 ... cycle() p p0, p1, … plast, p0, p1, … cycle('ABCD') → A B C D A B C D ... dropwhile() predicate, seq seq[n], seq[n+1], starting when predicate fails dropwhile(lambda x: x<5, [1,4,6,3,8]) → 6 3 8 filterfalse() predicate, seq elements of seq where predicate(elem) fails filterfalse(lambda x: x<5, [1,4,6,3,8]) → 6 8 groupby() iterable[, key] sub-iterators grouped by value of key(v) groupby(['A','B','DEF'], len) → (1, A B) (3, DEF) islice() seq, [start,] stop [, step] elements from seq[start:stop:step] islice('ABCDEFG', 2, None) → C D E F G pairwise() iterable (p[0], p[1]), (p[1], p[2]) pairwise('ABCDEFG') → AB BC CD DE EF FG repeat() elem [,n] elem, elem, elem, … endlessly or up to n times repeat(10, 3) → 10 10 10 starmap() func, seq func(*seq[0]), func(*seq[1]), … starmap(pow, [(2,5), (3,2), (10,3)]) → 32 9 1000 takewhile() predicate, seq seq[0], seq[1], until predicate fails takewhile(lambda x: x<5, [1,4,6,3,8]) → 1 4 tee() it, n it1, it2, … itn splits one iterator into n tee('ABC', 2) → A B C, A B C zip_longest() p, q, … (p[0], q[0]), (p[1], q[1]), … zip_longest('ABCD', 'xy', fillvalue='-') → Ax By C- D- Combinatoric iterators: Iterator Arguments Results product() p, q, … [repeat=1] cartesian product, equivalent to a nested for-loop permutations() p[, r] r-length tuples, all possible orderings, no repeated elements combinations() p, r r-length tuples, in sorted order, no repeated elements combinations_with_replacement() p, r r-length tuples, in sorted order, with repeated elements Examples Results product('ABCD', repeat=2) AA AB AC AD BA BB BC BD CA CB CC CD DA DB DC DD permutations('ABCD', 2) AB AC AD BA BC BD CA CB CD DA DB DC combinations('ABCD', 2) AB AC AD BC BD CD combinations_with_replacement('ABCD', 2) AA AB AC AD BB BC BD CC CD DD Itertool Functions ¶ The following functions all construct and return iterators.
Some provide streams of infinite length, so they should only be accessed by functions or loops that truncate the stream. itertools. accumulate ( iterable [ , function , * , initial=None ] ) ¶ Make an iterator that returns accumulated sums or accumulated results from other binary functions. The function defaults to addition. The function should accept two arguments, an accumulated total and a value from the iterable .
If an initial value is provided, the accumulation will start with that value and the output will have one more element than the input iterable. Roughly equivalent to: def accumulate ( iterable , function = operator . add , * , initial = None ): 'Return running totals' # accumulate([1,2,3,4,5]) → 1 3 6 10 15 # accumulate([1,2,3,4,5], initial=100) → 100 101 103 106 110 115 # accumulate([1,2,3,4,5], operator.mul) → 1 2 6 24 120 iterator = iter ( iterable ) total = initial if initial is None : try : total = next ( iterator ) except StopIteration : return yield total for element in iterator : total = function ( total , element ) yield total To compute a running minimum, set function to min() .
For a running maximum, set function to max() . Or for a running product, set function to operator.mul() . To build an amortization table , accumulate the interest and apply payments: >>> data = [ 3 , 4 , 6 , 2 , 1 , 9 , 0 , 7 , 5 , 8 ] >>> list ( accumulate ( data , max )) # running maximum [3, 4, 6, 6, 6, 9, 9, 9, 9, 9] >>> list ( accumulate ( data , operator . mul )) # running product [3, 12, 72, 144, 144, 1296, 0, 0, 0, 0] # Amortize a 5% loan of 1000 with 10 annual payments of 90 >>> update = lambda balance , payment : round ( balance * 1.05 ) - payment >>> list ( accumulate ( repeat ( 90 , 10 ), update , initial = 1_000 )) [1000, 960, 918, 874, 828, 779, 728, 674, 618, 559, 497] See functools.reduce() for a similar function that returns only the final accumulated value.
Added in version 3.2. Changed in version 3.3: Added the optional function parameter. Changed in version 3.8: Added the optional initial parameter. itertools. batched ( iterable , n , * , strict = False ) ¶ Batch data from the iterable into tuples of length n . The last batch may be shorter than n . If strict is true, will raise a ValueError if the final batch is shorter than n . Loops over the input iterable and accumulates data into tuples up to size n .
The input is consumed lazily, just enough to fill a batch. The result is yielded as soon as the batch is full or when the input iterable is exhausted : >>> flattened_data = [ 'roses' , 'red' , 'violets' , 'blue' , 'sugar' , 'sweet' ] >>> unflattened = list ( batched ( flattened_data , 2 )) >>> unflattened [('roses', 'red'), ('violets', 'blue'), ('sugar', 'sweet')] Roughly equivalent to: def batched ( iterable , n , * , strict = False ): # batched('ABCDEFG', 3) → ABC DEF G if n < 1 : raise ValueError ( 'n must be at least one' ) iterator = iter ( iterable ) while batch := tuple ( islice ( iterator , n )): if strict and len ( batch ) != n : raise ValueError ( 'batched(): incomplete batch' ) yield batch Added in version 3.12.
Changed in version 3.13: Added the strict option. itertools. chain ( * iterables ) ¶ Make an iterator that returns elements from the first iterable until it is exhausted , then proceeds to the next iterable, until all of the iterables are exhausted. This combines multiple data sources into a single iterator. Roughly equivalent to: def chain ( * iterables ): # chain('ABC', 'DEF') → A B C D E F for iterable in iterables : yield from iterable Note that unpacking in comprehensions provides similar functionality so that list(chain(p, q)) could be written as [*s for s in (p, q)] . classmethod chain. from_iterable ( iterable ) ¶ Alternate constructor for chain() .
Gets chained inputs from a single iterable argument that is evaluated lazily. Roughly equivalent to: def from_iterable ( iterables ): # chain.from_iterable(['ABC', 'DEF']) → A B C D E F for iterable in iterables : yield from iterable Note that unpacking in comprehensions provides similar functionality so that list(chain.from_iterable(iterables)) could be written as [*s for s in iterables] . itertools. combinations ( iterable , r ) ¶ Return r length subsequences of elements from the input iterable .
The output is a subsequence of product() keeping only entries that are subsequences of the iterable . The length of the output is given by math.comb() which computes n! / r! / (n - r)! when 0 ≤ r ≤ n or zero when r > n . The combination tuples are emitted in lexicographic order according to
The rest of this page is on the live site.