Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
a5b4b0d
Introduce a `functools.cached_method` decorator
sirosen May 18, 2026
1425819
Refine the implementation of cached_method
sirosen May 18, 2026
8ff6b31
Minor tweaks to cached_method docs
sirosen May 18, 2026
30f839b
Remove cached_method locking logic
sirosen May 19, 2026
9d109fa
Fix signature line in docs for cached_method
sirosen May 19, 2026
d26358a
Fix use of a latin abbreviation
sirosen May 19, 2026
0686932
Update Doc/library/functools.rst
sirosen May 28, 2026
262a53e
Update functools to 'lazy import weakref'
sirosen Jul 17, 2026
fffc5d3
Add `functools.cached_method` to What's New
sirosen Jul 17, 2026
57cc653
Merge branch 'main' into cached-method
sirosen Jul 18, 2026
06c2b18
Apply suggestions from code review
sirosen Jul 21, 2026
365c484
Apply suggestion from @StanFromIreland
sirosen Jul 21, 2026
981013b
Move `cached_method` above `cached_property`
sirosen Jul 21, 2026
8086aa5
Check type of 'maxsize' in cached_method
sirosen Jul 21, 2026
a7f206c
Fix race condition in cached_method
sirosen Jul 21, 2026
128ea42
Move the docstring for cached_method to public func
sirosen Jul 28, 2026
126cfa5
Update Doc/whatsnew/3.16.rst
sirosen Jul 29, 2026
4901223
Clarify `cached_method` behaviors per review
sirosen Nov 7, 2026
017bb4b
Apply batched suggestions from code review
sirosen Nov 10, 2026
fd18b9e
Fix cached_method with a bound method type
sirosen Nov 12, 2026
bd51b09
Enhance docs for cached_method
sirosen Nov 12, 2026
3a98f0f
Merge branch 'main' into cached-method
sirosen Nov 12, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions Doc/library/functools.rst
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,70 @@ The :mod:`!functools` module defines the following functions:
.. versionadded:: 3.9


.. decorator:: cached_method(func)
cached_method(maxsize=None, typed=False)

Decorator to wrap a method with a bounded or unbounded cache.

When :func:`cache` or :func:`lru_cache` are used on an instance method, the

@johnslavik johnslavik Nov 8, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about static methods, class methods, and properties?

I prefer that we explicitly rule these out in the docs or document how cached_method composes with @classmethod, @staticmethod, and @property, including which decorator orders are supported.

A few points to consider:

  1. Class methods with @cached_method vs. class methods with @lru_cache:

    class C:
        @classmethod
        @cached_method(maxsize=128)
        def method(cls, arg): ...

    This creates a separate cache for each class, whereas @classmethod + @lru_cache also works, but uses a shared cache whose keys include cls. In the latter case cls must be hashable, and refs to cls are kept in cache entries (which is mostly fine, as normally classes are long-lived and hashable).

    One limitation of the current composition is that C.method.cache_info() and C.method.cache_clear() are unavailable.

    Could we clarify whether this combination is supported and decide how users should inspect or clear its caches in this case?

  2. @staticmethod + @cached_method problems:

    class C:
        @staticmethod
        @cached_method
        def method(x):
            return x.value

    Here, the identity of x selects a separate cache, there is no C instance involved. If x supports weak references, this can appear to work, despite having different semantics from ordinary function caching.

    It also changes the calling convention, i.e. C.method(x=obj) fails because the wrapper does not preserve the original function's first parameter name. A static method with no arguments fails too, as does one whose first argument cannot be weakly referenced, such as an integer or string.

    Nowadays you can do:

    class C:
        @staticmethod
        @lru_cache(maxsize=128)
        def method(arg): ...

    Could the documentation explicitly recommend this pattern? or @cache, and discourage @staticmethod above @cached_method as unsuitable for general static methods? The inner decorator cannot generally detect the surrounding staticmethod at decoration time.

  3. @property + @cached_method:

    from dataclasses import dataclass
    from functools import cached_method
    from math import hypot
    
    @dataclass(frozen=True)
    class Point:
        __slots__ = ("x", "y", "__weakref__",)
        x: float
        y: float
    
        @property
        @cached_method
        def distance_from_origin(self) -> float:
            return hypot(self.x, self.y)
    
    
    if __name__ == "__main__":
        point = Point(3, 4)
        print(point.distance_from_origin)  # computes 5.0
        print(point.distance_from_origin)  # returns the cached value

    (This example uses explicit slots because dataclass(slots=True, weakref_slot=True) currently fails with this composition).

    This is now an alternative to cached_property with different semantics. It works without an instance __dict__, whereas cached_property requires a mutable instance dictionary. It also preserves ordinary property setter behavior. On otherwise mutable instances, a getter-only property prevents assignment, while cached_property permits overwriting the cached value. It would be nice to document (or rule out) this composition.

Finally, putting cached_method above classmethod, staticmethod, or property does not currently provide the corresponding descriptor behavior. It would help to document these unsupported orders, and consider clearer errors where the decorator can identify them.

Explicit support for an outer cached_method could be a separate API choice (which has its advantages, e.g. making cached_method idiomatic/intrinsic for methods, enforce only one way to make cached properties).

@sirosen sirosen Nov 10, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My inclination is to say that cached_method does not support static methods or classmethods. I don't think there's any strong reason that someone would want it for those cases, if they're also aware of the cache/lru_cache decorators. I'm also not sure how it could work even if we did want support, at least with cached_method as the inner decorator. I think a documentation addition is sufficient.

For property, supporting that composition was intentional -- @jaraco suggested it early in the process for this feature. To me it makes sense, since the methods decorated by properties (all of getters, setters, and deleters) behave like ordinary instance methods.
Although I like the idea of superseding cached_property, as you note they have different APIs. I'm personally against any deprecation in the near term.

It would help to document these unsupported orders, and consider clearer errors where the decorator can identify them.

I can work a bit on dedicated detection and error messages where possible. I think it should be possible to catch these all.

Explicit support for an outer cached_method could be a separate API choice (which has its advantages, e.g. making cached_method idiomatic/intrinsic for methods, enforce only one way to make cached properties).

I'm open to it in the future, but if we can agree to start without it, I'd be happier.

I think cached_method makes more sense as the inner decorator for property, and as the outer decorator for classmethod and staticmethod. But that is likely to confuse end users. And, as above, I'm not sure there's much compelling need for cached_method(classmethod(...)).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm trying hard to keep the docs short and easy to read, but I added a new paragraph and note-directive to address composition with property, classmethod, and staticmethod.

I'm aware that it technically works in some of the classmethod and staticmethod cases, so I'm simply documenting it as "unsupported", and intentionally not specifying what that means exactly. I hope that's satisfactory. I think trying to detect and raise a TypeError isn't worthwhile, given that it can only be done in a subset of cases.

instance (``self``) will be stored in the cache. As a result, instances cannot be
garbage collected until the relevant cache entries are cleared.
This decorator uses :func:`lru_cache`, but it wraps the unbound method to accept
a weakref and ensures that caches are cleared when instances are garbage collected.

This is useful for expensive computations which are consistent with respect to
an instance, for example, those which depend only on immutable attributes.

Example::

class DataSet:

def __init__(self, sequence_of_ints):
self._data = tuple(sequence_of_ints)

@cached_method
def shifted(self, shift):
return DataSet([value + shift for value in self._data])

On instances, :func:`cached_method` behaves very similarly to :func:`cache`,
providing :func:`!cache_info` and :func:`!cache_clear`.

:func:`cached_method` does not prevent all possible race conditions in
multi-threaded usage. The function could run more than once on the
same instance, with the same inputs, with the latest run setting the cached
value. The per-instance cache is lazily initialized on first access (via the
descriptor protocol), so parallel access on a single instance can race to
initialize.

This decorator requires that the instance supports weak references.
Some immutable types and slotted classes without ``__weakref__`` as one of
the defined slots will encounter errors when the cached method is first used.

Hashability is not required: the cache is indexed by the :func:`id` of
the instances. This also means that distinct instances always get distinct
caches, even if they compare and hash equal.

*maxsize* and *typed* are supported as keyword arguments to the decorator,
and are passed to the underlying :func:`lru_cache`.

Composition with :deco:`property` is supported, and has slightly different
mechanics from :func:`cached_property`. As a result, the two decorators can
be combined in cases where the instances do not have a ``__dict__`` -- for
example, on slotted classes.

.. note::

:func:`cached_method` does not support composition with
:deco:`classmethod` or :deco:`staticmethod`. Users who wish to have
caching on :func:`classmethod`\s and :func:`staticmethod`\s should use
:func:`cache` or :func:`lru_cache` instead.

Because an inner decorator sees a normal function, these combinations
cannot be reliably detected when the method is declared.

.. versionadded:: next


.. decorator:: cached_property(func)

Transform a method of a class into a property whose value is computed once
Expand Down
8 changes: 8 additions & 0 deletions Doc/whatsnew/3.16.rst
Original file line number Diff line number Diff line change
Expand Up @@ -500,6 +500,14 @@ encodings
(Contributed by Petr Viktorin in :gh:`157675`.)


functools
---------

* Added :func:`functools.cached_method` decorator for applying a cache to
instance methods.
(Contributed by Stephen Rosen in :gh:`102618`.)


gzip
----

Expand Down
128 changes: 121 additions & 7 deletions Lib/functools.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@
__all__ = ['update_wrapper', 'wraps', 'WRAPPER_ASSIGNMENTS', 'WRAPPER_UPDATES',
'total_ordering', 'cache', 'cmp_to_key', 'lru_cache', 'reduce',
'partial', 'partialmethod', 'singledispatch', 'singledispatchmethod',
'cached_property', 'Placeholder']
'cached_method', 'cached_property', 'Placeholder']

from abc import get_cache_token
from collections import namedtuple
# import weakref # Deferred to single_dispatch()
from operator import itemgetter
from reprlib import recursive_repr
from types import FunctionType, GenericAlias, MethodType, MappingProxyType, UnionType
from _thread import RLock
lazy import weakref

################################################################################
### update_wrapper() and wraps() decorator
Expand Down Expand Up @@ -884,11 +884,6 @@ def singledispatch(func):
implementations can be registered using the register() attribute of the
generic function.
"""
# There are many programs that use functools without singledispatch, so we
# trade-off making singledispatch marginally slower for the benefit of
# making start-up of such applications slightly faster.
import weakref

registry = {}
dispatch_cache = weakref.WeakKeyDictionary()
cache_token = None
Expand Down Expand Up @@ -1119,6 +1114,125 @@ def __wrapped__(self):
def register(self):
return self._unbound.register

################################################################################
### cached_method -- a version of lru_cache() which uses id(self)
################################################################################


class _bound_cached_method:
"""
A wrapper over a cached method which acts like a bound method.

It holds a reference to the instance and the caching variant of the
function, and it calls the function when called. This is constructed
dynamically whenever a cached method is accessed on an instance.
"""
def __init__(self, func, inst):
self.func = func
self.inst = inst

update_wrapper(self, self.func)

self.cache_clear = func.cache_clear
self.cache_info = func.cache_info
self.cache_parameters = func.cache_parameters

def __repr__(self):
return f"<bound cached method {self.func.__qualname__} of {self.inst!r}>"

def __call__(self, /, *args, **kwargs):
return self.func(*args, **kwargs)


def _cached_method_weakref_callback(cache_dict, id_key):
def callback(ref):
cache_dict.pop(id_key, None)
return callback


def _wrap_unbound_cached_method(ref, unbound_method, maxsize, typed):
@wraps(unbound_method)
@lru_cache(maxsize, typed)
def wrapped(*args, **kwargs):
return unbound_method(ref(), *args, **kwargs)
Comment thread
sirosen marked this conversation as resolved.
Resolved
return wrapped


class _cached_method:
def __init__(self, func, /, maxsize=None, typed=False):
self._function_table = {}

self._maxsize = maxsize
self._typed = typed

self.func = func
update_wrapper(self, func)

def __call__(self, instance, /, *args, **kwargs):
# a direct call skips construction of a bound cached method, since it
# isn't needed in order to guarantee that `instance` is not released
# before `cached_func` runs
cached_func = self._get_or_create_cached_func(instance)
return cached_func(*args, **kwargs)

def __repr__(self):
return f"<unbound cached method {self.func.__qualname__}>"

def __get__(self, instance, owner=None):
if instance is None:
return self
# construct a bound method, to guarantee that the instance cannot be
# released until after the returned function is called
unbound_func = self._get_or_create_cached_func(instance)
return _bound_cached_method(unbound_func, instance)

def _get_or_create_cached_func(self, instance):
instance_id = id(instance)

try:
ref, cached_func = self._function_table[instance_id]
except KeyError:
cb = _cached_method_weakref_callback(self._function_table, instance_id)
try:
ref = weakref.ref(instance, cb)
except TypeError as exc:
exc.__suppress_context__ = True
raise TypeError(
"`cached_method` requires the instances of "
f"{type(instance).__name__!r} to be weakly referencable"
) from exc

cached_func = _wrap_unbound_cached_method(
ref, self.func, self._maxsize, self._typed
)
self._function_table[instance_id] = ref, cached_func

return cached_func


def cached_method(func=None, /, maxsize=None, typed=False):
Comment thread
sirosen marked this conversation as resolved.
Resolved
"""
A caching decorator for use on instance methods.

Using cache or lru_cache on methods is problematic because the instance is put into
the cache and cannot be garbage collected until the cache is cleared. This decorator
uses a cache based on `id(self)` and a weakref to clear cache entries.

The instance must be weak-referencable.

By default, this provides an infinite sized cache similar to `functools.cache`. Use
*maxsize* and *typed* to set these attributes of the underlying LRU cache.
"""
if maxsize is not None and not isinstance(maxsize, int):
raise TypeError(
'Expected maxsize to be an integer or None')
if func is None:
def decorator(func):
return _cached_method(func, maxsize=maxsize, typed=typed)
Comment thread
sirosen marked this conversation as resolved.
Resolved
return decorator
else:
return _cached_method(func, maxsize=maxsize, typed=typed)


################################################################################
### cached_property() - property result cached as instance attribute
Expand Down
60 changes: 60 additions & 0 deletions Lib/test/test_functools.py
Original file line number Diff line number Diff line change
Expand Up @@ -3869,5 +3869,65 @@ def prop(self):
self.assertEqual(t.prop, 1)


class CachedValueAdder:
def __init__(self, value):
self.value = value

@py_functools.cached_method
def add(self, other):
return self.value + other


class TestCachedMethod(unittest.TestCase):
module = py_functools

def test_cached_usage(self):
one = CachedValueAdder(1)
self.assertEqual(one.add(2), 3)
one.value = 2
self.assertEqual(one.add(2), 3) # still 3, not 4
one.add.cache_clear()
self.assertEqual(one.add(2), 4) # now 4

def test_cache_info(self):
one = CachedValueAdder(1)
self.assertEqual(one.add.cache_info(),
self.module._CacheInfo(hits=0, misses=0, maxsize=None, currsize=0))
for _ in range(3):
for i in range(10):
one.add(i)
self.assertEqual(one.add.cache_info(),
self.module._CacheInfo(hits=20, misses=10, maxsize=None, currsize=10))
one.add.cache_clear()
self.assertEqual(one.add.cache_info(),
self.module._CacheInfo(hits=0, misses=0, maxsize=None, currsize=0))

def test_reapplication_is_allowed(self):
decorator = py_functools.cached_method(maxsize=10)

class MyObject:
@decorator
def a(self):
return 1

@decorator
def b(self):
return 2

x = MyObject()
self.assertEqual(x.a(), 1)
self.assertEqual(x.b(), 2)

def test_cached_method_under_property(self):
class MyObject:
@property
@py_functools.cached_method
def foo(self):
return 1

x = MyObject()
self.assertEqual(x.foo, 1)


if __name__ == '__main__':
unittest.main()
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Added a new ``functools.cached_method`` decorator, which uses weakrefs and
avoids putting ``self`` into the cache.
Loading