This page describes the functional programming tools available in Python 3, and how to use them.

Itertools: iterators for efficient looping

This module implements many iterator building blocks inspired by constructs from APL, Haskell, and SML. Each was recast in a form suitable for Python.

  • Itertools: iterators for efficient looping
  • Operator: standard operators as functions
  • Python overview
  • Linux commands help

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), etc. The same effect can be achieved in Python by combining map() and count() to form map(f, count()).

These tools and their built-in counterparts also work well with the high-speed functions in the operator module. For example, the multiplication operator can be mapped across two vectors to form an efficient dot-product: sum(map(operator.mul, vector1, vector2)).

Itertools functions

The following module 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 recipes

The extended tools offer the same high performance as the underlying toolset. The superior memory performance is kept by processing elements one at a time rather than bringing the whole iterable into memory all at once. Code volume is kept small by linking the tools together in a functional style which helps eliminate temporary variables. High speed is retained by preferring “vectorized” building blocks over the use of for-loops and generators which incur interpreter overhead.

def accumulate(iterable, func=operator.add): ‘Return running totals’ # accumulate([1,2,3,4,5]) –> 1 3 6 10 15 # accumulate([1,2,3,4,5], operator.mul) –> 1 2 6 24 120 it = iter(iterable) total = next(it) yield total for element in it: total = func(total, element) yield total

data = [3, 4, 6, 2, 1, 9, 0, 7, 5, 8]»> list(accumulate(data, operator.mul)) # running product[3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]»> list(accumulate(data, max)) # running maximum[3, 4, 6, 6, 6, 9, 9, 9, 9, 9]# Amortize a 5% loan of 1000 with 4 annual payments of 90»> cashflows = [1000, -90, -90, -90, -90]»> list(accumulate(cashflows, lambda bal, pmt: bal*1.05 + pmt))[1000, 960.0, 918.0, 873.9000000000001, 827.5950000000001]# Chaotic recurrence relation http://en.wikipedia.org/wiki/Logistic_map>>> logistic_map = lambda x, _: r * x * (1 - x)»> r = 3.8»> x0 = 0.4»> inputs = repeat(x0, 36) # only the initial value is used»> [format(x, ‘.2f’) for x in accumulate(inputs, logistic_map)][‘0.40’, ‘0.91’, ‘0.30’, ‘0.81’, ‘0.60’, ‘0.92’, ‘0.29’, ‘0.79’, ‘0.63’, ‘0.88’, ‘0.39’, ‘0.90’, ‘0.33’, ‘0.84’, ‘0.52’, ‘0.95’, ‘0.18’, ‘0.57’, ‘0.93’, ‘0.25’, ‘0.71’, ‘0.79’, ‘0.63’, ‘0.88’, ‘0.39’, ‘0.91’, ‘0.32’, ‘0.83’, ‘0.54’, ‘0.95’, ‘0.20’, ‘0.60’, ‘0.91’, ‘0.30’, ‘0.80’, ‘0.60’]

def chain(*iterables): # chain(‘ABC’, ‘DEF’) –> A B C D E F for it in iterables: for element in it: yield element

def from_iterable(iterables): # chain.from_iterable([‘ABC’, ‘DEF’]) –> A B C D E F for it in iterables: for element in it: yield element

def combinations(iterable, r): # combinations(‘ABCD’, 2) –> AB AC AD BC BD CD # combinations(range(4), 3) –> 012 013 023 123 pool = tuple(iterable) n = len(pool) if r > n: return indices = list(range(r)) yield tuple(pool[i] for i in indices) while True: for i in reversed(range(r)): if indices[i] != i + n - r: break else: return indices[i] += 1 for j in range(i+1, r): indices[j] = indices[j-1] + 1 yield tuple(pool[i] for i in indices)

def combinations(iterable, r): pool = tuple(iterable) n = len(pool) for indices in permutations(range(n), r): if sorted(indices) == list(indices): yield tuple(pool[i] for i in indices)

def combinations_with_replacement(iterable, r): # combinations_with_replacement(‘ABC’, 2) –> AA AB AC BB BC CC pool = tuple(iterable) n = len(pool) if not n and r: return indices = [0] * r yield tuple(pool[i] for i in indices) while True: for i in reversed(range(r)): if indices[i] != n - 1: break else: return indices[i:] = [indices[i] + 1] * (r - i) yield tuple(pool[i] for i in indices)

def combinations_with_replacement(iterable, r): pool = tuple(iterable) n = len(pool) for indices in product(range(n), repeat=r): if sorted(indices) == list(indices): yield tuple(pool[i] for i in indices)

def compress(data, selectors): # compress(‘ABCDEF’, [1,0,1,0,1,1]) –> A C E F return (d for d, s in zip(data, selectors) if s)

def count(start=0, step=1): # count(10) –> 10 11 12 13 14 … # count(2.5, 0.5) -> 2.5 3.0 3.5 … n = start while True: yield n n += step

def cycle(iterable): # cycle(‘ABCD’) –> A B C D A B C D A B C D … saved = [] for element in iterable: yield element saved.append(element) while saved: for element in saved: yield element

def dropwhile(predicate, iterable): # dropwhile(lambda x: x<5, [1,4,6,4,1]) –> 6 4 1 iterable = iter(iterable) for x in iterable: if not predicate(x): yield x break for x in iterable: yield x

def filterfalse(predicate, iterable): # filterfalse(lambda x: x%2, range(10)) –> 0 2 4 6 8 if predicate is None: predicate = bool for x in iterable: if not predicate(x): yield x

groups = []uniquekeys = []data = sorted(data, key=keyfunc)for k, g in groupby(data, keyfunc): groups.append(list(g)) # Store group iterator as a list uniquekeys.append(k)

class groupby: # [k for k, g in groupby(‘AAAABBBCCDAABBB’)] –> A B C D A B # [list(g) for k, g in groupby(‘AAAABBBCCD’)] –> AAAA BBB CC D def init(self, iterable, key=None): if key is None: key = lambda x: x self.keyfunc = key self.it = iter(iterable) self.tgtkey = self.currkey = self.currvalue = object() def iter(self): return self def next(self): while self.currkey == self.tgtkey: self.currvalue = next(self.it) # Exit on StopIteration self.currkey = self.keyfunc(self.currvalue) self.tgtkey = self.currkey return (self.currkey, self._grouper(self.tgtkey)) def _grouper(self, tgtkey): while self.currkey == tgtkey: yield self.currvalue self.currvalue = next(self.it) # Exit on StopIteration self.currkey = self.keyfunc(self.currvalue)

def islice(iterable, *args): # islice(‘ABCDEFG’, 2) –> A B # islice(‘ABCDEFG’, 2, 4) –> C D # islice(‘ABCDEFG’, 2, None) –> C D E F G # islice(‘ABCDEFG’, 0, None, 2) –> A C E G s = slice(*args) it = iter(range(s.start or 0, s.stop or sys.maxsize, s.step or 1)) nexti = next(it) for i, element in enumerate(iterable): if i == nexti: yield element nexti = next(it)

def permutations(iterable, r=None): # permutations(‘ABCD’, 2) –> AB AC AD BA BC BD CA CB CD DA DB DC # permutations(range(3)) –> 012 021 102 120 201 210 pool = tuple(iterable) n = len(pool) r = n if r is None else r if r > n: return indices = list(range(n)) cycles = list(range(n, n-r, -1)) yield tuple(pool[i] for i in indices[:r]) while n: for i in reversed(range(r)): cycles[i] -= 1 if cycles[i] == 0: indices[i:] = indices[i+1:] + indices[i:i+1] cycles[i] = n - i else: j = cycles[i] indices[i], indices[-j] = indices[-j], indices[i] yield tuple(pool[i] for i in indices[:r]) break else: return

def permutations(iterable, r=None): pool = tuple(iterable) n = len(pool) r = n if r is None else r for indices in product(range(n), repeat=r): if len(set(indices)) == r: yield tuple(pool[i] for i in indices)

def product(*args, repeat=1): # product(‘ABCD’, ‘xy’) –> Ax Ay Bx By Cx Cy Dx Dy # product(range(2), repeat=3) –> 000 001 010 011 100 101 110 111 pools = [tuple(pool) for pool in args] * repeat result = [[]] for pool in pools: result = [x+[y] for x in result for y in pool] for prod in result: yield tuple(prod)

def repeat(object, times=None): # repeat(10, 3) –> 10 10 10 if times is None: while True: yield object else: for i in range(times): yield object

list(map(pow, range(10), repeat(2)))[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

def starmap(function, iterable): # starmap(pow, [(2,5), (3,2), (10,3)]) –> 32 9 1000 for args in iterable: yield function(*args)

def takewhile(predicate, iterable): # takewhile(lambda x: x<5, [1,4,6,4,1]) –> 1 4 for x in iterable: if predicate(x): yield x else: break

def tee(iterable, n=2): it = iter(iterable) deques = [collections.deque() for i in range(n)] def gen(mydeque): while True: if not mydeque: # when the local deque is empty newval = next(it) # fetch a new value and for d in deques: # load it to all the deques d.append(newval) yield mydeque.popleft() return tuple(gen(d) for d in deques)

class ZipExhausted(Exception): passdef zip_longest(*args, **kwds): # zip_longest(‘ABCD’, ‘xy’, fillvalue=’-’) –> Ax By C- D- fillvalue = kwds.get(‘fillvalue’) counter = len(args) - 1 def sentinel(): nonlocal counter if not counter: raise ZipExhausted counter -= 1 yield fillvalue fillers = repeat(fillvalue) iterators = [chain(it, sentinel(), fillers) for it in args] try: while iterators: yield tuple(map(next, iterators)) except ZipExhausted: pass

def take(n, iterable): “Return first n items of the iterable as a list” return list(islice(iterable, n)) def tabulate(function, start=0): “Return function(0), function(1), …” return map(function, count(start)) def consume(iterator, n): “Advance the iterator n-steps ahead. If n is none, consume entirely.” # Use functions that consume iterators at C speed. if n is None: # feed the entire iterator into a zero-length deque collections.deque(iterator, maxlen=0) else: # advance to the empty slice starting at position n next(islice(iterator, n, n), None) def nth(iterable, n, default=None): “Returns the nth item or a default value” return next(islice(iterable, n, None), default) def quantify(iterable, pred=bool): “Count how many times the predicate is true” return sum(map(pred, iterable)) def padnone(iterable): “““Returns the sequence elements and then returns None indefinitely. Useful for emulating the behavior of the built-in map() function. "”” return chain(iterable, repeat(None)) def ncycles(iterable, n): “Returns the sequence elements n times” return chain.from_iterable(repeat(tuple(iterable), n)) def dotproduct(vec1, vec2): return sum(map(operator.mul, vec1, vec2)) def flatten(listOfLists): “Flatten one level of nesting” return chain.from_iterable(listOfLists) def repeatfunc(func, times=None, *args): “““Repeat calls to func with specified arguments. Example: repeatfunc(random.random) "”” if times is None: return starmap(func, repeat(args)) return starmap(func, repeat(args, times)) def pairwise(iterable): “s -> (s0,s1), (s1,s2), (s2, s3), …” a, b = tee(iterable) next(b, None) return zip(a, b) def grouper(iterable, n, fillvalue=None): “Collect data into fixed-length chunks or blocks” # grouper(‘ABCDEFG’, 3, ‘x’) –> ABC DEF Gxx” args = [iter(iterable)] * n return zip_longest(*args, fillvalue=fillvalue) def roundrobin(*iterables): “roundrobin(‘ABC’, ‘D’, ‘EF’) –> A D E B F C” # Recipe credited to George Sakkis pending = len(iterables) nexts = cycle(iter(it).next for it in iterables) while pending: try: for next in nexts: yield next() except StopIteration: pending -= 1 nexts = cycle(islice(nexts, pending)) def partition(pred, iterable): ‘Use a predicate to partition entries into false entries and true entries’ # partition(is_odd, range(10)) –> 0 2 4 6 8 and 1 3 5 7 9 t1, t2 = tee(iterable) return filterfalse(pred, t1), filter(pred, t2) def powerset(iterable): “powerset([1,2,3]) –> () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)” s = list(iterable) return chain.from_iterable(combinations(s, r) for r in range(len(s)+1)) def unique_everseen(iterable, key=None): “List unique elements, preserving order. Remember all elements ever seen.” # unique_everseen(‘AAAABBBCCDAABBB’) –> A B C D # unique_everseen(‘ABBCcAD’, str.lower) –> A B C D seen = set() seen_add = seen.add if key is None: for element in filterfalse(seen.contains, iterable): seen_add(element) yield element else: for element in iterable: k = key(element) if k not in seen: seen_add(k) yield element def unique_justseen(iterable, key=None): “List unique elements, preserving order. Remember only the element just seen.” # unique_justseen(‘AAAABBBCCDAABBB’) –> A B C D A B # unique_justseen(‘ABBCcAD’, str.lower) –> A B C A D return map(next, map(itemgetter(1), groupby(iterable, key))) def iter_except(func, exception, first=None): "”" Call a function repeatedly until an exception is raised. Converts a call-until-exception interface to an iterator interface. Like builtins.iter(func, sentinel) but uses an exception instead of a sentinel to end the loop. Examples: iter_except(functools.partial(heappop, h), IndexError) # priority queue iterator iter_except(d.popitem, KeyError) # non-blocking dict iterator iter_except(d.popleft, IndexError) # non-blocking deque iterator iter_except(q.get_nowait, Queue.Empty) # loop over a producer Queue iter_except(s.pop, KeyError) # non-blocking set iterator """ try: if first is not None: yield first() # For database APIs needing an initial cast to db.first() while 1: yield func() except exception: pass def first_true(iterable, default=False, pred=None): “““Returns the first true value in the iterable. If no true value is found, returns default If pred is not None, returns the first item for which pred(item) is true. "”” # first_true([a,b,c], x) –> a or b or c or x # first_true([a,b], x, f) –> a if f(a) else b if f(b) else x return next(filter(pred, iterable), default) def random_product(*args, repeat=1): “Random selection from itertools.product(*args, **kwds)” pools = [tuple(pool) for pool in args] * repeat return tuple(random.choice(pool) for pool in pools) def random_permutation(iterable, r=None): “Random selection from itertools.permutations(iterable, r)” pool = tuple(iterable) r = len(pool) if r is None else r return tuple(random.sample(pool, r)) def random_combination(iterable, r): “Random selection from itertools.combinations(iterable, r)” pool = tuple(iterable) n = len(pool) indices = sorted(random.sample(range(n), r)) return tuple(pool[i] for i in indices) def random_combination_with_replacement(iterable, r): “Random selection from itertools.combinations_with_replacement(iterable, r)” pool = tuple(iterable) n = len(pool) indices = sorted(random.randrange(n) for i in range(r)) return tuple(pool[i] for i in indices)

Note, many of the above recipes can be optimized by replacing global lookups with local variables defined as default values. For example, the dotproduct recipe can be written as:

def dotproduct(vec1, vec2, sum=sum, map=map, mul=operator.mul): return sum(map(mul, vec1, vec2))

Operator: standard operators as functions

The operator module exports a set of efficient functions corresponding to the intrinsic operators of Python. For example, operator.add(x, y) is equivalent to the expression x+y. The function names are those used for special class methods; variants without leading and trailing __ are also provided for convenience.

The functions fall into categories that perform object comparisons, logical operations, mathematical operations and sequence operations.

The object comparison functions are useful for all objects, and are named after the rich comparison operators they support:

The logical operations are also generally applicable to all objects, and support truth tests, identity tests, and boolean operations:

The mathematical and bitwise operations are the most numerous:

Operations which work with sequences (some of them with mappings too) include:

Example: Build a dictionary that maps the ordinals from 0 to 255 to their character equivalents.

d = {} keys = range(256) vals = map(chr, keys) map(operator.setitem, [d]*len(keys), keys, vals)

The operator module also defines tools for generalized attribute and item lookups. These are useful for making fast field extractors as arguments for map(), sorted(), itertools.groupby(), or other functions that expect a function argument.

Mapping operators to functions

This table shows how abstract operations correspond to operator symbols in the Python syntax and the functions in the operator module.

  • After f = attrgetter(’name’), the call f(b) returns b.name.After f = attrgetter(’name’, ‘date’), the call f(b) returns (b.name, b.date).After f = attrgetter(’name.first’, ’name.last’), the call f(b) returns (b.name.first, b.name.last).

def attrgetter(*items): if any(not isinstance(item, str) for item in items): raise TypeError(‘attribute name must be a string’) if len(items) == 1: attr = items[0] def g(obj): return resolve_attr(obj, attr) else: def g(obj): return tuple(resolve_attr(obj, attr) for attr in items) return gdef resolve_attr(obj, attr): for name in attr.split(”."): obj = getattr(obj, name) return obj

  • After f = itemgetter(2), the call f(r) returns r[2].After g = itemgetter(2, 5, 3), the call g(r) returns (r[2], r[5], r[3]).

def itemgetter(*items): if len(items) == 1: item = items[0] def g(obj): return obj[item] else: def g(obj): return tuple(obj[item] for item in items) return g

itemgetter(1)(‘ABCDEFG’)‘B’»> itemgetter(1,3,5)(‘ABCDEFG’)(‘B’, ‘D’, ‘F’)»> itemgetter(slice(2,None))(‘ABCDEFG’)‘CDEFG’v

inventory = [(‘apple’, 3), (‘banana’, 2), (‘pear’, 5), (‘orange’, 1)]»> getcount = itemgetter(1)»> list(map(getcount, inventory))[3, 2, 5, 1]»> sorted(inventory, key=getcount)[(‘orange’, 1), (‘banana’, 2), (‘apple’, 3), (‘pear’, 5)]

  • After f = methodcaller(’name’), the call f(b) returns b.name().After f = methodcaller(’name’, ‘foo’, bar=1), the call f(b) returns b.name(‘foo’, bar=1).

def methodcaller(name, *args, **kwargs): def caller(obj): return getattr(obj, name)(*args, **kwargs) return caller

“Inplace” operators

Many operations have an “in-place” version. Listed below are functions providing a more primitive access to in-place operators than the usual syntax does; for example, the statement x += y is equivalent to x = operator.iadd(x, y). Another way to put it is to say that z = operator.iadd(x, y) is equivalent to the compound statement z = x; z += y.

In those examples, note that when an in-place method is called, the computation and assignment are performed in two separate steps. The in-place functions listed below only do the first step, calling the in-place method. The second step, assignment, is not handled.

For immutable targets such as strings, numbers, and tuples, the updated value is computed, but not assigned back to the input variable:

a = ‘hello’ iadd(a, ’ world’) ‘hello world’ a ‘hello’

For mutable targets such as lists and dictionaries, the inplace method performs the update, so no subsequent assignment is necessary:

s = [‘h’, ’e’, ’l’, ’l’, ‘o’] iadd(s, [’ ‘, ‘w’, ‘o’, ‘r’, ’l’, ’d’]) [‘h’, ’e’, ’l’, ’l’, ‘o’, ’ ‘, ‘w’, ‘o’, ‘r’, ’l’, ’d’] s [‘h’, ’e’, ’l’, ’l’, ‘o’, ’ ‘, ‘w’, ‘o’, ‘r’, ’l’, ’d’]