Functional programming in Python 3

Updated: 03/13/2021 by Computer Hope
Python command

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.

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.accumulate(iterable [, func])
 Make an iterator that returns accumulated sums. Elements may be any addable type including Decimal or Fraction. If the optional func argument is supplied, it should be a function of two arguments and it will be used instead of addition.

Equivalent to:

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
There are many uses for the func argument. It can be set to min() for a running minimum, max() for a running maximum, or operator.mul() for a running product. Amortization tables can be built by accumulating interest and applying payments. First-order recurrence relations can be modeled by supplying the `initial value in the iterable and using only the accumulated total in func argument:

>>> 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']
See functools.reduce() for a similar function that returns only the final accumulated value. 
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. Used for treating consecutive sequences as a single sequence. Equivalent to:

def chain(*iterables): # chain('ABC', 'DEF') --> A B C D E F for it in iterables: for element in it: yield element
 
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 it in iterables: for element in it: yield element
 
itertools.combinations(iterable, r)
 Return r length subsequences of elements from the input iterable.

Combinations are emitted in lexicographic sort order. So, if the input iterable is sorted, the combination tuples will be produced in sorted order.

Elements are treated as unique based on their position, not on their value. So if the input elements are unique, there will be no repeat values in each combination.

Equivalent to:

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)
The code for combinations() can be also expressed as a subsequence of permutations() after filtering entries where the elements are not in sorted order (according to their position in the input pool):

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)
The number of items returned is n! / r! / (n-r)! when 0 <= r <= n or zero when r > n. 
itertools.combinations_with_replacement(iterable,  r)
 Return r length subsequences of elements from the input iterable allowing individual elements to be repeated more than once.

Combinations are emitted in lexicographic sort order. So, if the input iterable is sorted, the combination tuples will be produced in sorted order.

Elements are treated as unique based on their position, not on their value. So if the input elements are unique, the generated combinations will also be unique.

Equivalent to:

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)
The code for combinations_with_replacement() can be also expressed as a subsequence of product() after filtering entries where the elements are not in sorted order (according to their position in the input pool):

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)
The number of items returned is (n+r-1)! / r! / (n-1)! when n > 0. 
itertools.compress(data,  selectors)
 Make an iterator that filters elements from data returning only those that have a corresponding element in selectors that evaluates to True. Stops when either the data or selectors iterables is exhausted. Equivalent to:

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)
 
itertools.count(start=0,  step=1)
 Make an iterator that returns evenly spaced values starting with number start. Often used as an argument to map() to generate consecutive data points. Also, used with zip() to add sequence numbers. Equivalent to:

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
When counting with floating point numbers, better accuracy can sometimes be achieved by substituting multiplicative code such as: (start + step * i for i in count()).		 
itertools.cycle(iterable)
 Make an iterator returning elements from the iterable and saving a copy of each. When the iterable is exhausted, return elements from the saved copy. Repeats indefinitely. Equivalent to:

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
Note, this member of the toolkit may require significant auxiliary storage (depending on the length of the iterable). 
itertools.dropwhile(predicate,  iterable)
 Make an iterator that drops elements from the iterable as long as the predicate is true; afterwards, returns every element. Note, the iterator does not produce any output until the predicate first becomes false, so it may have a lengthy start-up time. Equivalent to:

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
 
itertools.filterfalse(predicate,  iterable)
 Make an iterator that filters elements from iterable returning only those for which the predicate is False. If predicate is None, return the items that are false. Equivalent to:

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
 
itertools.groupby(iterable, key=None)
 Make an iterator that returns consecutive keys and groups from the iterable. The key is a function computing a key value for each element. If not specified or is None, key defaults to an identity function and returns the element unchanged. Generally, the iterable needs to already be sorted on the same key function.

The operation of groupby() is similar to the uniq filter in Unix. It generates a break or new group every time the value of the key function changes (which is why it is usually necessary to have sorted the data using the same key function). That behavior differs from SQL's GROUP BY which aggregates common elements regardless of their input order.

The returned group is itself an iterator that shares the underlying iterable with groupby(). Because the source is shared, when the groupby() object is advanced, the previous group is no longer visible. So, if that data is needed later, it should be stored as a list:

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)
groupby() is equivalent to:

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)
 
itertools.islice(iterable,  stop)itertools.islice(iterable,  start,  stop[,  step])
 Make an iterator that returns selected elements from the iterable. If start is non-zero, then elements from the iterable are skipped until start is reached. Afterward, elements are returned consecutively unless step is set higher than one which results in items being skipped. If stop is None, then iteration continues until the iterator is exhausted, if at all; otherwise, it stops at the specified position. Unlike regular slicing, islice() does not support negative values for start, stop, or step. Can be used to extract related fields from data where the internal structure was flattened (for example, a multi-line report may list a name field on every third line). Equivalent to:

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)
If start is None, then iteration starts at zero. If step is None, then the step defaults to one. 
itertools.permutations(iterable,  r=None)
 Return successive r length permutations of elements in the iterable.

If r is not specified or is None, then r defaults to the length of the iterable and all possible full-length permutations are generated.

Permutations are emitted in lexicographic sort order. So, if the input iterable is sorted, the permutation tuples will be produced in sorted order.

Elements are treated as unique based on their position, not on their value. So if the input elements are unique, there will be no repeat values in each permutation.

Equivalent to:

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
The code for permutations() can be also expressed as a subsequence of product(), filtered to exclude entries with repeated elements (those from the same position in the input pool):

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)
The number of items returned is n! / (n-r)! when 0 <= r <= n or zero when r > n. 
itertools.product(*iterables,  repeat=1)
 Cartesian product of input iterables.

Equivalent to nested for-loops in a generator expression. For example, product(A, B) returns the same as ((x,y) for x in A for y in B).

The nested loops cycle like an odometer with the rightmost element advancing on every iteration. This pattern creates a lexicographic ordering so that if the input's iterables are sorted, the product tuples are emitted in sorted order.

To compute the product of an iterable with itself, specify the number of repetitions with the optional repeat keyword argument. For example, product(A, repeat=4) means the same as product(A, A, A, A).

This function is equivalent to the following code, except that the actual implementation does not build up intermediate results in memory:

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)
 
itertools.repeat(object[,  times])
 Make an iterator that returns object over and over again. Runs indefinitely unless the times argument is specified. Used as argument to map() for invariant parameters to the called function. Also, used with zip() to create an invariant part of a tuple record. Equivalent to:

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
A common use for repeat is to supply a stream of constant values to map or zip:

>>> list(map(pow, range(10), repeat(2)))[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
 
itertools.starmap(function,  iterable)
 Make an iterator that computes the function using arguments obtained from the iterable. Used instead of map() when argument parameters are already grouped in tuples from a single iterable (the data was “pre-zipped”). The difference between map() and starmap() parallels the distinction between function(a,b) and function(*c). Equivalent to:

def starmap(function, iterable): # starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000 for args in iterable: yield function(*args)
 
itertools.takewhile(predicate,  iterable)
 Make an iterator that returns elements from the iterable as long as the predicate is true. Equivalent to:

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
 
itertools.tee(iterable, n=2)
 Return n independent iterators from a single iterable. Equivalent to:

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)
Once tee() has made a split, the original iterable should not be used anywhere else; otherwise, the iterable could get advanced without the tee objects being informed.

This itertool may require significant auxiliary storage (depending on how much temporary data needs to be stored). In general, if one iterator uses most or all of the data before another iterator starts, it is faster to use list() instead of tee(). 
itertools.zip_longest(*iterables,  fillvalue=None)
 Make an iterator that aggregates elements from each of the iterables. If the iterables are of uneven length, missing values are filled-in with fillvalue. Iteration continues until the longest iterable is exhausted. Equivalent to:

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
If one of the iterables is potentially infinite, then the zip_longest() function should be wrapped with something that limits the number of calls (for example islice() or takewhile()). If not specified, fillvalue defaults to None.

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

operator.lt(a, b)operator.le(a, b)operator.eq(a, b)operator.ne(a, b)operator.ge(a, b)operator.gt(a, b)operator.__lt__(a, b)operator.__le__(a, b)operator.__eq__(a, b)operator.__ne__(a, b)operator.__ge__(a, b)operator.__gt__(a, b)
 Perform “rich comparisons” between a and b. Specifically, lt(a, b) is equivalent to a < b, le(a, b) is equivalent to a <= b, eq(a, b) is equivalent to a == b, ne(a, b) is equivalent to a != b, gt(a, b) is equivalent to a > b and ge(a, b) is equivalent to a >= b. Note that these functions can return any value, which may or may not be interpretable as a Boolean value.

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

operator.not_(obj)operator.__not__(obj)
 Return the outcome of not obj. (Note that there is no __not__() method for object instances; only the interpreter core defines this operation. The result is affected by the __bool__() and __len__() methods.) 
operator.truth(obj)
 Return True if obj is true, and False otherwise. This is equivalent to using the bool constructor. 
operator.is_(a, b)
 Return a is b. Tests object identity. 
operator.is_not(a, b)
 Return a is not b. Tests object identity.

The mathematical and bitwise operations are the most numerous:

operator.abs(obj)operator.__abs__(obj)
 Return the absolute value of obj. 
operator.add(a, b)operator.__add__(a, b)
 Return a + b, for a and b numbers. 
operator.and_(a, b)operator.__and__(a, b)
 Return the bitwise and of a and b. 
operator.floordiv(a, b)operator.__floordiv__(a, b)
 Return a // b. 
operator.index(a)operator.__index__(a)
 Return a converted to an integer. Equivalent to a.__index__(). 
operator.inv(obj)operator.invert(obj)operator.__inv__(obj)operator.__invert__(obj)
 Return the bitwise inverse of the number obj. This is equivalent to ~obj. 
operator.lshift(a, b)operator.__lshift__(a, b)
 Return a shifted left by b. 
operator.mod(a, b)operator.__mod__(a, b)
 Return a % b. 
operator.mul(a, b)operator.__mul__(a, b)
 Return a * b, for a and b numbers. 
operator.neg(obj)operator.__neg__(obj)
 Return obj negated (-obj). 
operator.or_(a, b)operator.__or__(a, b)
 Return the bitwise or of a and b. 
operator.pos(obj)operator.__pos__(obj)
 Return obj positive (+obj). 
operator.pow(a, b)operator.__pow__(a, b)
 Return a ** b, for a and b numbers. 
operator.rshift(a, b)operator.__rshift__(a, b)
 Return a shifted right by b. 
operator.sub(a, b)operator.__sub__(a, b)
 Return a - b. 
operator.truediv(a, b)operator.__truediv__(a, b)
 Return a / b where 2/3 is .66 rather than 0. This is also known as “true” division. 
operator.xor(a, b)operator.__xor__(a, b)
 Return the bitwise exclusive or of a and b.

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

operator.concat(a, b)operator.__concat__(a, b)
 Return a + b for a and b sequences. 
operator.contains(a, b)operator.__contains__(a, b)
 Return the outcome of the test b in a. Note the reversed operands. 
operator.countOf(a, b)
 Return the number of occurrences of b in a. 
operator.delitem(a, b)operator.__delitem__(a, b)
 Remove the value of a at index b. 
operator.getitem(a, b)operator.__getitem__(a, b)
 Return the value of a at index b. 
operator.indexOf(a, b)
 Return the index of the first of occurrence of b in a. 
operator.setitem(a, b, c)operator.__setitem__(a, b, c)
 Set the value of a at index b to c.

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)   

operator.length_hint(obj, default=0)
 Return an estimated length for the object o. First try to return its actual length, then an estimate using object.__length_hint__(), and finally return the default value.

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.

operator.attrgetter(attr)operator.attrgetter(*attrs)
 Return a callable object that fetches attr from its operand. If more than one attribute is requested, returns a tuple of attributes. The attribute names can also contain dots. For example:

  • 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
 
operator.itemgetter(item)operator.itemgetter(*items)
 Return a callable object that fetches item from its operand using the operand's __getitem__() method. If multiple items are specified, returns a tuple of lookup values. For example:

  • 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]).
Equivalent to:

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
The items can be any type accepted by the operand's __getitem__() method. Dictionaries accept any hashable value. Lists, tuples, and strings accept an index or a slice:

>>> itemgetter(1)('ABCDEFG')'B'>>> itemgetter(1,3,5)('ABCDEFG')('B', 'D', 'F')>>> itemgetter(slice(2,None))('ABCDEFG')'CDEFG'v
Example of using itemgetter() to retrieve specific fields from a tuple record:

>>> 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)]
 
operator.methodcaller(name[,  args...])
 Return a callable object that calls the method name on its operand. If additional arguments and/or keyword arguments are given, they will be given to the method as well. For example:

  • 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).
Equivalent to:

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

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.

Operation Syntax Function
Addition 
a + b
 
add(a, b)
Concatenation 
seq1 + seq2
 
concat(seq1, seq2)
Containment Test 
obj in seq
 
contains(seq, obj)
Division 
a / b
 
truediv(a, b)
Division 
a // b
 
floordiv(a, b)
Bitwise And 
a & b
 
and_(a, b)
Bitwise Exclusive Or 
a ^ b
 
xor(a, b)
Bitwise Inversion 
~ a
 
invert(a)
Bitwise Or 
a | b
 
or_(a, b)
Exponentiation 
a ** b
 
pow(a, b)
Identity 
a is b
 
is_(a, b)
Identity 
a is not b
 
is_not(a, b)
Indexed Assignment 
obj[k] = v
 
setitem(obj, k, v)
Indexed Deletion 
del obj[k]
 
delitem(obj, k)
Indexing 
obj[k]
 
getitem(obj, k)
Left Shift 
a << b
 
lshift(a, b)
Modulo 
a % b
 
mod(a, b)
Multiplication 
a * b
 
mul(a, b)
Negation (Arithmetic) 
- a
 
neg(a)
Negation (Logical) 
not a
 
not_(a)
Positive 
+ a
 
pos(a)
Right Shift 
a >> b
 
rshift(a, b)
Slice Assignment 
seq[i:j] = values
 
setitem(seq, slice(i, j), values)
Slice Deletion 
del seq[i:j]
 
delitem(seq, slice(i, j))
Slicing 
seq[i:j]
 
getitem(seq, slice(i, j))
String Formatting 
s % obj
 
mod(s, obj)
Subtraction 
a - b
 
sub(a, b)
Truth Test 
obj
 
truth(obj)
Ordering 
a < b
 
lt(a, b)
Ordering 
a <= b
 
le(a, b)
Equality 
a == b
 
eq(a, b)
Difference 
a != b
 
ne(a, b)
Ordering 
a >= b
 
ge(a, b)
Ordering 
a > b
 
gt(a, b)

"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']
operator.iadd(a, b)operator.__iadd__(a, b)
 a = iadd(a, b) is equivalent to a += b. 
operator.iand(a, b)operator.__iand__(a, b)
 a = iand(a, b) is equivalent to a &= b. 
operator.iconcat(a, b)operator.__iconcat__(a, b)
 a = iconcat(a, b) is equivalent to a += b for a and b sequences. 
operator.ifloordiv(a, b)operator.__ifloordiv__(a, b)
 a = ifloordiv(a, b) is equivalent to a //= b. 
operator.ilshift(a, b)operator.__ilshift__(a, b)
 a = ilshift(a, b) is equivalent to a <<= b. 
operator.imod(a, b)operator.__imod__(a, b)
 a = imod(a, b) is equivalent to a %= b. 
operator.imul(a, b)operator.__imul__(a, b)
 a = imul(a, b) is equivalent to a *= b. 
operator.ior(a, b)operator.__ior__(a, b)
 a = ior(a, b) is equivalent to a |= b. 
operator.ipow(a, b)operator.__ipow__(a, b)
 a = ipow(a, b) is equivalent to a **= b. 
operator.irshift(a, b)operator.__irshift__(a, b)
 a = irshift(a, b) is equivalent to a >>= b. 
operator.isub(a, b)operator.__isub__(a, b)
 a = isub(a, b) is equivalent to a -= b. 
operator.itruediv(a, b)operator.__itruediv__(a, b)
 a = itruediv(a, b) is equivalent to a /= b. 
operator.ixor(a, b)operator.__ixor__(a, b)
 a = ixor(a, b) is equivalent to a ^= b.