Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Standard Library: Data Structures and Functional Tools

The functools module

Reference for Python's functools module: wraps, cached_property, total_ordering, singledispatch, cmp_to_key, partial, reduce and cache, with runnable examples.

functools collects tools for functions that act on or return other functions: caching, partial application, decorators that preserve metadata, and class helpers that fill in missing methods.

The caching decorators and the partial and reduce tools have focused pages: cache and lru_cache and partial and reduce.

Python
from functools import wraps, total_ordering

Try it

Python wraps and total_ordering

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python singledispatch, cached_property, cmp_to_key

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Syntax

Python
from functools import wraps, total_ordering, singledispatch, cached_property, cmp_to_key
Name Description
wraps(wrapped) Decorator for wrapper functions; copies __name__, __doc__, __module__ and more, and sets __wrapped__.
update_wrapper(wrapper, wrapped) The function behind wraps.
total_ordering Class decorator: define __eq__ and one of <, <=, >, >=, and it fills in the rest.
singledispatch Turns a function into a generic function that picks an implementation by the type of the first argument.
singledispatchmethod The same for methods.
cached_property Computes an attribute once per instance and stores it (3.8+).
cmp_to_key(func) Wraps an old-style two-argument comparison for use as a key=.
cache, lru_cache Memoization (see the cache page).
partial, partialmethod, reduce See the partial and reduce page.

Return value: a decorator, wrapper or new callable, depending on the tool. Raises: ValueError from total_ordering if no ordering method is defined; TypeError from singledispatch registration without a usable type annotation.

Usage notes

  • Always use @wraps in decorators. Without it, the wrapped function reports the wrapper's name and docstring, which breaks introspection and debugging output.
  • total_ordering is convenient, not fast. The generated methods are slower than hand-written ones. For plain data, consider a dataclass with order=True.
  • singledispatch dispatches on the first argument only and follows the class hierarchy (a bool goes to the int implementation unless bool is registered). Register with annotations or an explicit type.
  • cached_property needs an instance __dict__, so it does not work with __slots__ classes unless __dict__ is a slot. Delete the attribute to clear the cache.
  • cached_property has no lock since Python 3.12; two threads can compute the value at the same time. Add your own lock if the computation must run once.
  • cmp_to_key is for migration. Prefer a real key function; it is faster and clearer.
  • Python 3.9+ added cache, a simpler unbounded lru_cache(maxsize=None).