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.
from functools import wraps, total_ordering
Try it
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.
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
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
@wrapsin decorators. Without it, the wrapped function reports the wrapper's name and docstring, which breaks introspection and debugging output. total_orderingis convenient, not fast. The generated methods are slower than hand-written ones. For plain data, consider a dataclass withorder=True.singledispatchdispatches on the first argument only and follows the class hierarchy (aboolgoes to theintimplementation unlessboolis registered). Register with annotations or an explicit type.cached_propertyneeds an instance__dict__, so it does not work with__slots__classes unless__dict__is a slot. Delete the attribute to clear the cache.cached_propertyhas 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_keyis for migration. Prefer a real key function; it is faster and clearer.- Python 3.9+ added
cache, a simpler unboundedlru_cache(maxsize=None).