functools: lru_cache, partial, reduce

Published by Brayan K

The functools module is a standard-library toolkit of higher-order helpers that transform or extend functions — adding caching, pre-filling arguments, folding sequences, and preserving metadata.

Part of the free Python course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

A cache decides whether the function body runs

Memoization means remembering a result so a later call can reuse it. lru_cache wraps a function with that behaviour. A hit returns a stored result without running the body; a miss runs the function and stores its result. The list below records evaluations only to make that difference visible, not because logging is a good reason to cache a function.

from functools import lru_cache

evaluated = []
@lru_cache(maxsize=2)
def square(number):
    evaluated.append(number)
    return number * number

print([square(number) for number in [2, 3, 2]])
print("evaluated:", evaluated)
info = square.cache_info()
print("hits:", info.hits, "misses:", info.misses, "entries:", info.currsize)

# ✅ Expected output:
# [4, 9, 4]
# evaluated: [2, 3]
# hits: 1 misses: 2 entries: 2

The cache trusts its arguments to describe the result. It does not notice a changed file, configuration value or global variable. Functional Programming Techniques in Python owns that hidden-input/purity problem; here the focus is choosing and controlling the cache.

Decorator construction and metadata preservation belong to Decorators & Advanced Features. Higher-order calls are introduced in Higher-Order Functions & Function Factories (Python); the utilities below supply concrete policies for them.

Least recently used is not simply oldest inserted

A bounded cache evicts the entry that has gone longest without being used. Reading an existing entry refreshes its recency. The sequence below revisits one key before adding a third key, then asks for the evicted key again.

from functools import lru_cache

evaluated = []
@lru_cache(maxsize=2)
def square(number):
    evaluated.append(number)
    return number * number

print([square(number) for number in [2, 3, 2, 4, 3]])
print("evaluated:", evaluated)
info = square.cache_info()
print(info.hits, info.misses, info.currsize)
square.cache_clear()
info = square.cache_info()
print("after clearing:", info.hits, info.misses, info.currsize)

# ✅ Expected output:
# [4, 9, 4, 16, 9]
# evaluated: [2, 3, 4, 3]
# 1 4 2
# after clearing: 0 0 0

maxsize limits the number of entries, not their total bytes. The cache keeps references to its argument keys and results until they are evicted or cleared. functools.cache is the unbounded form, equivalent to lru_cache(maxsize=None); use it only when you accept the lifetime and possible growth of those retained entries.

The cache’s bookkeeping is thread-safe, but concurrent misses can still compute the same call more than once. It is not an exactly-once execution mechanism. These lifetime and concurrency rules are documented in the Python lru_cache reference.

Choose keys and results that are safe to retain

The arguments used as cache keys must be hashable. A list can change after a call, so passing it directly to this cached total fails before the function body runs. Converting a finite collection of numbers to a tuple gives the call an immutable key; a tuple containing a list would still be unhashable.

from functools import lru_cache

@lru_cache(maxsize=4)
def total(values):
    return sum(values)

print(total([2, 3]))

# ✅ Expected error:
# TypeError: unhashable type: 'list'
from functools import lru_cache

@lru_cache(maxsize=4)
def total(values):
    return sum(values)

values = [2, 3]
print(total(tuple(values)))
values.append(4)
print(total(tuple(values)))
print(total((2, 3)))

# ✅ Expected output:
# 5
# 9
# 5

A cache also returns the stored result object, not a fresh copy. If callers expect independent lists, caching a list-producing function can make one caller’s edits visible to another caller.

from functools import cache

@cache
def steps():
    return ["read", "test"]

first = steps()
first.append("publish")
second = steps()
print(second)
print(first is second)

# ✅ Expected output:
# ['read', 'test', 'publish']
# True
from functools import cache

@cache
def steps():
    return ("read", "test")

mine = list(steps())
mine.append("publish")
print(mine)
print(steps())

# ✅ Expected output:
# ['read', 'test', 'publish']
# ('read', 'test')

Do not cache a generator when callers need a fresh iteration, or an async function when callers need a fresh coroutine. Cache reusable result data instead. The same question applies to ordinary objects: is sharing this exact result part of the function’s contract?

Cache a computed attribute on each instance

cached_property computes an attribute when it is first read, then stores the result on that instance. Read it without parentheses. Unlike a regular property, later reads normally use the stored value without calling the getter again; changing the inputs does not invalidate that value.

from functools import cached_property

class Basket:
    def __init__(self, prices):
        self.prices = tuple(prices)

    @cached_property
    def total(self):
        print("calculate")
        return sum(self.prices)

first = Basket([2, 3])
second = Basket([7])
print(first.total)
print(first.total)
first.prices = (10, 20)
print("still cached:", first.total)
del first.total
print("recalculated:", first.total)
print("other instance:", second.total)
first.total = 99
print("assigned:", first.total)

# ✅ Expected output:
# calculate
# 5
# 5
# still cached: 5
# calculate
# recalculated: 30
# calculate
# other instance: 7
# assigned: 99

Deleting the cached attribute allows the getter to run on its next read. Assigning to that name instead supplies a replacement value, which takes precedence. There is no cache_clear() method for this attribute. Decide whether the object's inputs will stay fixed or where your application will invalidate the cached result.

cached_property stores the value in the instance's writable __dict__. A class with __slots__ and no __dict__ cannot use it. Properties & Descriptors owns attribute lookup and the property protocol; the choice here is whether retaining a computed value is appropriate.

Do not rely on exactly one getter call under concurrent access. Python 3.12 removed cached_property's older lock, so code needing synchronization must provide it. The cached_property reference documents the storage and concurrency rules.

Partial fills arguments; it does not call the function yet

partial() creates a callable that supplies some arguments on a later call. Stored positional arguments are placed before new positional arguments. Stored keyword arguments act as defaults that a later keyword can override; “frozen arguments” does not mean that every choice is permanently locked.

from functools import partial

def price(quantity, *, unit_cost):
    return quantity * unit_cost

notebooks = partial(price, unit_cost=250)
print(notebooks(3))
print(notebooks(3, unit_cost=200))

# ✅ Expected output:
# 750
# 600

Positional binding starts at the left. Filling the base of a power function does not fill its exponent. Use a named argument when the intended slot is later in the signature, then avoid supplying that same slot again positionally.

from functools import partial

def power(base, exponent):
    return base ** exponent

two_to = partial(power, 2)
square = partial(power, exponent=2)
print(two_to(3))
print(square(3))

# ✅ Expected output:
# 8
# 9

The stored objects are referenced, not deeply copied. Changing a mutable object already supplied to partial changes what the later call sees. *args & **kwargs owns the argument-binding rules; partial applies those rules when the saved and new arguments meet.

Reduce carries an accumulator from left to right

reduce() combines the current accumulator with one more item at a time. Without an initial value it starts from the first item. Subtraction makes the direction visible: this is a left fold, not a right-associated expression and not an automatic parallel calculation.

from functools import reduce

def subtract(accumulator, value):
    print("combine:", accumulator, value)
    return accumulator - value

print("result:", reduce(subtract, [20, 3, 2]))

# ✅ Expected output:
# combine: 20 3
# combine: 17 2
# result: 15

An empty iterable has no first value from which to start. Supply an explicit initial value when empty input is valid. Pass that initial value positionally here so the example works across Python 3.11–3.14.

from functools import reduce

print(reduce(lambda total, value: total + value, []))

# ✅ Expected error:
# TypeError: reduce() of empty iterable with no initial value
from functools import reduce

def append_digit(number, digit):
    return number * 10 + digit

print(reduce(append_digit, [3, 1, 4], 0))
print(reduce(append_digit, [], 0))

# ✅ Expected output:
# 314
# 0

Use sum() for an ordinary sum, math.prod() for a product, or a plain loop when that makes the changing state clearer. reduce is useful when the accumulator operation itself expresses the problem; using it for every loop usually hides rather than explains the work.

Create a reusable label formatter

Fill the two defaults supplied by partial, then call the resulting formatter twice. The second call should replace the stored prefix while retaining the stored separator. This is a small test that the settings are defaults, not an immutable policy.

from functools import partial

def label(value, *, prefix, separator):
    return prefix + separator + value

item_label = partial(label, prefix=___, separator=___)
print(item_label("A"))
print(item_label("B", prefix="box"))

# 👉 replace ___ with "item"
# 👉 replace ___ with ":"

# ✅ Expected output:
# item:A
# box:B

Reuse parsed values while reporting a batch

Each line below contains a binary price string and a quantity. Create a binary parser using partial(int, base=2), then cache decoding with at most four entries. Calculate and print each line total, the batch total, and the cache’s hit and miss counts. Keep quantities outside the cache key: decoding a price should be reused even when the requested quantity changes.

This tiny conversion makes reuse easy to inspect; it is not evidence that caching cheap int() calls improves speed. In a real parser, measure the actual workload before choosing a cache. Use sum for the total rather than introducing reduce where an existing operation already says what you mean.

from functools import lru_cache, partial

parse_binary = partial(int, base=2)
@lru_cache(maxsize=4)
def decode(price_text):
    return parse_binary(price_text)

lines = [("101", 2), ("11", 1), ("101", 1)]
totals = [decode(text) * quantity for text, quantity in lines]
print(totals)
print("total:", sum(totals))
info = decode.cache_info()
print("hits:", info.hits, "misses:", info.misses)

# ✅ Expected output:
# [10, 3, 5]
# total: 18
# hits: 1 misses: 2

Practice quiz

What does this program print? from functools import lru_cache @lru_cache(maxsize=2) def square(n): print("compute", n) return n * n print(square(3)) print(square(3))

  • compute 3 9 compute 3 9
  • compute 3 9 9
  • 9 9
  • compute 3 3 3

Answer: compute 3 9 9. A hit returns the stored result without running the body again.

What does this program print? from functools import lru_cache @lru_cache(maxsize=2) def f(n): return n for n in [1, 2, 1, 3, 2]: f(n) info = f.cache_info() print(info.hits, info.misses)

  • 2 3
  • 0 5
  • 3 2
  • 1 4

Answer: 1 4. Reusing 1 refreshes it, so adding 3 evicts 2; the final 2 is a miss.

What does this program print? from functools import partial def scale(n, factor): return n * factor double = partial(scale, factor=2) print(double(4, factor=3))

  • 12
  • 8
  • TypeError
  • 4

Answer: 12. A later keyword overrides the stored keyword default.

What does this program print? from functools import partial def subtract(a, b): return a - b from_ten = partial(subtract, 10) print(from_ten(3))

  • -7
  • 13
  • 7
  • TypeError

Answer: 7. Stored positional values are prepended, so the call subtracts from ten.

What does this program print? from functools import cache @cache def values(): return [] values().append(2) print(values())

  • []
  • [2]
  • None
  • TypeError

Answer: [2]. The cached result is the same list, including the caller’s mutation.

What does this program print? from functools import reduce print(reduce(lambda a, b: a - b, [20, 3, 2]))

  • 19
  • 25
  • -25
  • 15

Answer: 15. The left fold computes (20 - 3) - 2.

What does this program print? from functools import reduce print(reduce(lambda a, b: a + b, [], 10))

  • 10
  • 0
  • None
  • TypeError

Answer: 10. With no items, reduce returns the supplied initial value.

What does this program print? from functools import cached_property class Box: def __init__(self): self.value = 2 @cached_property def doubled(self): return self.value * 2 b = Box() print(b.doubled) b.value = 5 print(b.doubled) del b.doubled print(b.doubled)

  • 4 10 10
  • 4 4 4
  • 4 4 10
  • AttributeError

Answer: 4 4 10. Changing value leaves the cached attribute intact. Deleting doubled allows the next read to compute from the new value.

Continue this course

Related lessons