functools

Tools for working with functions: remembering results (lru_cache), partial calls (partial), and folding collections (reduce).

On this page

Example

#
Python
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())
Resultsaved result, you can check it
55
23416728348467685
CacheInfo(hits=79, misses=81, maxsize=None, currsize=81)

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

#
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. The maxsize parameter (default 128) sets how many results to remember, and None removes the limit.
  • @cache

    decorator

    A simpler equivalent of lru_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). Without initial, an empty collection raises TypeError.
  • @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

#
partial(): a function with fixed arguments
Python
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"))
Resultsaved result, you can check it
Emma: +5 EXP (task)
Jack: +20 EXP (7-day streak)
10
reduce(): folding a collection into one value
Python
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))
Resultsaved result, you can check it
319
95
{'name': 'Emma', 'level': 3, 'points': 250}
1
total_ordering: a full set of comparisons
Python
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))
Resultsaved result, you can check it
True True False

Good practices

#
  • Do not use @lru_cache for 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, use sum(), math.prod(), and max(). They are more readable and faster.

Related entries

#

Practise it in lessons

#

Spotted a mistake or missing an example? Write to us.