functools
Tools for working with functions: remembering results (lru_cache), partial calls (partial), and folding collections (reduce).
Example
#from functools import lru_cache
@lru_cache(maxsize=None)
def fib(n):
if n < 2:
return n
return fib(n - 1) + fib(n - 2)
print(fib(10))
print(fib(80))
print(fib.cache_info())Without @lru_cache, computing fib(80) would take tens of quadrillions of function calls, which is decades of work even for a fast computer. With the cache, each value is computed only once.
Definition and usage
#The functools module contains tools for working with functions: ones that take functions as arguments, wrap them, or build new ones from them. The parts used most often are the @lru_cache decorator, the partial() and reduce() functions, and the @wraps decorator, which is essential when writing your own decorators.
@lru_cache remembers a functionโs results for arguments it has already seen. On the next call with the same arguments, the result is returned immediately, without recomputing, which gives a huge speedup for expensive calculations and recursion. The arguments must be hashable (numbers, strings, tuples), and the result should depend only on them. Hit statistics are shown by the cache_info() method.
partial() creates a new function with some of the arguments fixed, e.g. partial(int, base=2) creates a function that converts strings written in binary into numbers. reduce() folds a collection into a single value: it calls a two-argument function first on the first two items, then on the result and the third item, and so on. For sums and maximums, though, sum() and max() are simpler.
Syntax
#from functools import cache, lru_cache, partial, reduce, wraps
@lru_cache(maxsize=128)
def function(arguments):
...
new = partial(function, *args, **kwargs)
result = reduce(function, iterable, initial)The most important functions
#@lru_cache
decorator
Remembers results for the most recently used arguments. Themaxsizeparameter (default 128) sets how many results to remember, andNoneremoves the limit.@cache
decorator
A simpler equivalent oflru_cache(maxsize=None): remembers all results.partial()
function
Returns a new function with some of the arguments fixed:partial(func, *args, **kwargs).reduce()
function
Folds a collection into a single value:reduce(func, iterable, initial). Withoutinitial, an empty collection raisesTypeError.@wraps
decorator
Used in your own decorators: copies the name and docstring of the wrapped function to the wrapper.@total_ordering
class decorator
Fills in the missing comparisons based on__eq__and one of the methods__lt__,__le__,__gt__, or__ge__.@cached_property
method decorator
Turns a method into an attribute that is computed once, on first read.
More examples
#from functools import partial
def award(exp, name, reason="task"):
return f"{name}: +{exp} EXP ({reason})"
small = partial(award, 5)
streak = partial(award, 20, reason="7-day streak")
print(small("Emma"))
print(streak("Jack"))
from_binary = partial(int, base=2)
print(from_binary("1010"))from functools import reduce
scores = [72, 95, 64, 88]
print(reduce(lambda total, s: total + s, scores))
print(reduce(lambda best, s: s if s > best else best, scores))
updates = [{"level": 2}, {"points": 250}, {"level": 3}]
profile = reduce(lambda acc, change: {**acc, **change}, updates, {"name": "Emma"})
print(profile)
print(reduce(lambda a, b: a * b, [], 1))from functools import total_ordering
@total_ordering
class Level:
def __init__(self, number):
self.number = number
def __eq__(self, other):
return self.number == other.number
def __lt__(self, other):
return self.number < other.number
print(Level(3) >= Level(2), Level(1) <= Level(1), Level(5) > Level(7))Good practices
#- Do not use
@lru_cachefor functions with side effects, e.g. writing to a file, drawing random numbers, or reading the time. For remembered arguments, the function will not run at all. - The arguments of a cached function must be hashable. Convert lists to tuples before calling.
- Instead of
reduce()for a sum, product, or maximum, usesum(),math.prod(), andmax(). They are more readable and faster.
Related entries
#- DecoratorsFunctions that wrap other functions and add behavior to them, such as logging or permission checks. Written as @name.
- lambdaA short anonymous function written as a single expression.
- map()Calls a function for every item and returns an iterator of results.
- sum()Adds together all the numbers in a collection.
- @propertyTurns a method into an attribute: the value is computed on read, and an optional setter controls writes.
- itertoolsTools for working with iterators: chaining, grouping, combinations, and infinite sequences.
Practise it in lessons
#Spotted a mistake or missing an example? Write to us.