Python · Module

functools

Python’s functools module provides higher-order-function tools for adapting, decorating, caching, reducing, and dispatching callable objects. It includes utilities such as cache, lru_cache, partial, reduce, singledispatch, wraps, and update_wrapper.

How it works

Import functools utilities when a program needs to manipulate callable objects: decorators can preserve metadata, caches can reuse results, partial can pre-fill arguments, reduce can fold an iterable, and singledispatch can select an implementation by the first argument's type.

Syntax

import functools
functools.cache(user_function)
functools.lru_cache(maxsize=128, typed=False)
functools.partial(func, /, *args, **keywords)
functools.reduce(function, iterable, /, initial=_initial_missing)
functools.singledispatch(func)
functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

Parameters

Name	Type	Description
`callable`	`callable`	A callable accepted by the selected functools utility, such as the function passed to reduce, partial, cache, or a decorator.
`iterable_or_arguments`	`iterable / positional and keyword arguments`	For reduce, an iterable whose elements are combined from left to right; for cache decorators, function arguments form the cache key.
`initial_or_maxsize`	`object / int or None`	Optional starting accumulator for reduce, or the maximum number of recent entries retained by lru_cache.

Returns

The module provides functions, decorators, and callable objects; individual APIs return wrapped callables, partial callables, reduced values, or dispatching generic functions as documented.

Key points

The module groups helpers for composing, adapting, decorating, caching, and dispatching callable objects.
Instances implementing __call__ can be used with functools APIs as callable values.
reduce folds an iterable into one result, optionally starting from an initial value.
singledispatch chooses an implementation according to the type of the first argument and supports registrations for additional types.
lru_cache stores recent results and evicts entries according to least-recently-used order when its bound is reached.
Decorator wrappers expose the wrapped callable through __wrapped__, supporting introspection and controlled bypassing.

Common mistakes

Caching requires every argument to be hashable; mutable or otherwise unhashable arguments cannot serve as cache keys.
An unbounded cache can consume increasing memory; choose a bounded cache when the input space is large.

Example: Memoize recursive computation

from functools import cache

@cache
def fibonacci(n: int) -> int:
    if n < 2:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))
print(fibonacci.cache_info())

The decorator memoizes each result, so repeated recursive calls reuse cached values.

When to use it

Memoize expensive calls

Recursive or repeated pure computations receive the same arguments.

Pre-fill callable arguments

A callback needs a fixed configuration value while retaining the callback interface.

Implement type-based dispatch

Different input types need specialized behavior behind one public function.

Fold an iterable

A sequence must be accumulated into one value with a custom binary operation.

Interview questions

QWhat problem does functools solve?

functools is a module for higher-order functions, meaning functions that act on or return other functions. Its utilities operate on callable objects generally, not only ordinary function definitions.

Follow-up: How would you preserve a decorated function's metadata? Use functools.wraps, which applies update_wrapper to the wrapper and copies the wrapped function's relevant attributes.

QHow does functools.cache work?

functools.cache creates a thin wrapper around a function and stores results for previously seen arguments. It is equivalent to an unbounded lru_cache and is useful when repeated calls have identical, hashable arguments.

Follow-up: When would lru_cache be preferable? Use it when maxsize should limit retained entries or when LRU statistics and cache management are needed.

QWhat does functools.partial do?

partial returns a callable that behaves like the original function with positional and keyword arguments pre-filled. Arguments supplied later are appended positionally, while later keyword values extend or override the stored keywords.

Follow-up: How can dispatch be based on argument type instead? Decorate a base function with singledispatch and register implementations for supported types.

functools.cache
functools.cached_property
functools.lru_cache
functools.partial
functools.reduce
functools.singledispatch
functools.singledispatchmethod
functools.update_wrapper

Source: functools — Higher-order functions and operations on callable objects. Checked 2026-10-15.