Skip to content

gh-102618: Introduce a functools.cached_method decorator - #150002

Open
sirosen wants to merge 22 commits into
python:mainfrom
sirosen:cached-method
Open

sirosen wants to merge 22 commits into
python:mainfrom
sirosen:cached-method

Conversation

@sirosen

@sirosen sirosen commented May 18, 2026 •

Copy link
Copy Markdown
Contributor

resolves #102618

This definition of cached_method is based on the discussion on DPO:
https://discuss.python.org/t/107164

Some tradeoffs need to be made in any version of such a decorator. In this particular implementation, the choices made are as follows:

  • lru_cache will be used under the hood, and cache_clear() and cache_info() will be exposed

  • caches will be stored in a separate dict, indexed by id(self) -- meaning instances do not need to be hashable and will not share caches

  • weakrefs will be used to delete entries from the cache, so the instances must be weak-referencable

  • lru_cache itself is not threadsafe, but initialization of the caches is threadsafe -- this avoids confusing scenarios in which cache entries "disappear"
    EDIT: in response to review feedback, this locking was removed; users can lock if they want thread safety

New documentation is included, marked for 3.16, and a small number of new
tests are added.


In addition to @rhettinger's review, as the listed owner for functools, @sobolevn expressed interest in reviewing changes.
@kenahoo and @stevendaprano may also want a look based on their prior interest.

Everyone I've spoken with about this change1 has been supportive of the core idea. In particular @jaraco noted that he would support this addition, and maintains a very different implementation. There are many other ways of writing this, with different tradeoffs. Perhaps the most notable class of those are versions which store caches on the instance itself, like this one suggested here in the DPO discussion -- this writes the cached method into __dict__, similarly to cached_property.

Of course, I'm happy to alter or re-approach any part of this per review! 😄

Footnotes

  1. at PyCon US 2026 ↩

@read-the-docs-community

read-the-docs-community Bot commented May 18, 2026 •

Copy link
Copy Markdown

resolves python#102618

This definition of `cached_method` is based on the discussion on DPO:
   https://discuss.python.org/t/107164

Some tradeoffs need to be made in any version of such a decorator. In
this particular implementation, the choices made are as follows:

- lru_cache will be used under the hood, and `cache_clear()` and
  `cache_info()` will be exposed

- caches will be stored in a separate dict, indexed by `id(self)` --
  meaning instances do not need to be hashable and will not share caches

- weakrefs will be used to delete entries from the cache, so the
  instances must be weak-referencable

- lru_cache itself is not threadsafe, but initialization of the caches
  is threadsafe -- this avoids confusing scenarios in which cache entries
  "disappear"

New documentation is included, marked for 3.16, and a small number of new
tests are added.
Comment thread Lib/functools.py Resolved
Comment thread Lib/functools.py Resolved
sirosen and others added 2 commits May 18, 2026 16:51
Thanks to feedback from @jaraco, this adjustment makes the public
interface for `cached_method` a function which is responsible for the
argument management, rather than trying to use `__call__` on the
descriptor itself.

This frees up `__call__` to lookup the relevant LRU-cached function and
invoke it, which makes the `_cached_method` descriptor suitable for use
as a `property.fget` callable.

Tests are updated to indicate that a decorator can be prepared and then
used repeatedly (which was previously an explicit error), and can be used
under a property decorator.
- Fix doc references
- Use imperative mood in a comment

Co-authored-by: Jason R. Coombs <308610+jaraco@users.noreply.github.com>
@sirosen

sirosen commented May 18, 2026

Copy link
Copy Markdown
Contributor Author

Jelle pointed out to me that although I have tried to be careful about the locking I included, to minimize contention, the lock I defined is per-cached_method, meaning it is defined per-class. With many instances of the same class in parallel threads, users would potentially see lock contention.
My initial instinct on this was to look for a way to make the locking per-instance, but having been referred to this DPO thread which addressed the same topic for cached_property, there's a strong case for just removing the lock.

I'll push a change to remove the locking and clarify the thread-safety documentation.

@sirosen

sirosen commented May 19, 2026

Copy link
Copy Markdown
Contributor Author

@willingc , this is the PR that I mentioned to you; you said you wanted a ping to take a look. 🙂

Comment thread Lib/functools.py Resolved
Comment thread Lib/functools.py Resolved
sirosen added 2 commits May 19, 2026 11:02
Although this logic tried to avoid lock contention, there were still
scenarios under which it was possible and could negatively impact users.
Removal and adjustment of the documentation puts responsibility for
locking/safety onto users, similar to other parts of the stdlib.
Comment thread Doc/library/functools.rst Resolved
@GrahamDumpleton

GrahamDumpleton commented May 24, 2026 •

Copy link
Copy Markdown

FWIW. The wrapt package has a lru_cache helper which still uses functools.lru_cache internally, but which uses wrapt to provide a single decorator which will work on any of functions, instance methods, class methods etc. This was released in wrapt 2.0.0, but had been added well before even knew about this PR:

Comment thread Doc/library/functools.rst Resolved
Co-authored-by: Edgar Ramírez Mondragón <16805946+edgarrmondragon@users.noreply.github.com>

@jaraco jaraco left a comment

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.

In my opinion, this implementation is fairly clean and simple. The documentation shows pretty clearly what the user's expectations should be. The tradeoffs chosen have been well considered and a reasonable path elected. I propose to get this merged and give it some exposure through the beta releases. From there iterate or pivot.

@StanFromIreland StanFromIreland left a comment

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.

This needs a What's New in 3.16 entry.

sirosen added 2 commits July 16, 2026 20:58
Rather than doing an old-style deferred import, with explanatory comments
for why the deferred import style is used. Convert these to a top-level
`lazy import weakref`.

No explanatory comment is used, on the grounds that the new syntax is
sufficiently low in cognitive cost that experienced maintainers will
quickly recognize it and assume that the pattern is used to either break
a cycle or reduce import costs.
@sirosen
sirosen requested a review from AA-Turner as a code owner July 17, 2026 02:11
@sirosen

sirosen commented Jul 17, 2026 •

Copy link
Copy Markdown
Contributor Author

I've applied the lazy import change. My commit message explains why I did not preserve any comment about it, but I'm open to feedback on that.

I also added the What's New entry.
Should I go ahead and merge main back into this branch? (I don't want to do that prematurely; maybe I should leave it for the final approval+merge?) (Confirmed quickly with someone that I should.)

@hugovk hugovk left a comment

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.

We have docs tooling that will update next to whatever the next pre-release is, for example:

"Added in version 3.16.0a0 (unreleased)"

Comment thread Doc/library/functools.rst Resolved
Comment thread Doc/library/functools.rst Resolved
Comment thread Doc/library/functools.rst Resolved
Comment thread Doc/whatsnew/3.16.rst Resolved
Comment thread Lib/functools.py Resolved
Comment thread Lib/functools.py Resolved
Comment thread Lib/functools.py Resolved
Comment thread Lib/functools.py Resolved
Comment thread Doc/library/functools.rst Resolved
Comment thread Lib/functools.py Resolved
sirosen and others added 7 commits July 21, 2026 13:55
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <stan@python.org>
Co-authored-by: Stan Ulbrych <stan@python.org>
And add it to functools' `__all__` list.
Multiple weakrefs can be created when there are concurrent writes to a
"new cache". When they finalize, their attempts to clear the dict should
be kept safe by using a pop() default.
In order for `help(functools.cached_method)` to show the docstring, it
needs to be attached to the public interface, not the implementation.

This docstring was "misplaced" in the course of refactors to this code
during review.
Co-authored-by: Stan Ulbrych <stan@python.org>
@sirosen

sirosen commented Aug 6, 2026

Copy link
Copy Markdown
Contributor Author

I just saw #154069 . If that goes in, this should get updated to also use setdefault when initializing the lookup table.
If that merges first, I intend to update this PR.

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown

This PR is stale because it has been open for 90 days with no activity.

@github-actions github-actions Bot added the stale Stale PR or inactive for long period of time. label Nov 5, 2026
@rhettinger

Copy link
Copy Markdown
Contributor

The docs should specify what happens in code like this:

@dataclass
class Equity:
    str: symbol

    @cached_method(maxsize=16)
    def opening_price(self, date):
        return expensive_query(self.symbol, date)

e1 = Equity('GOOG')
print(e1.opening_price, date(2020, 2, 20))  # Miss  ? Unhashable instances allowed
print(e1.opening_price, date(2020, 2, 20))  # Hit
print(e1.opening_price, date(2020, 2, 25))  # Miss

e2 = Equity('GOOG')
print(e2.opening_price, date(2020, 2, 20))  # ? Cross-instance caching

e1.symbol = 'ALPB'
print(e1.opening_price, date(2020, 2, 20))  # ? Detect attribute change

del e1                                      # ? Immediate clear

Comment thread Doc/library/functools.rst Outdated

When :func:`cache` or :func:`lru_cache` are used on an instance method, the
instance (``self``) will be stored in the cache. As a result, instances cannot be
garbage collected until the relevant caches are cleared.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

or until the entry ages out of the lru (pretty much like any other entry).

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.

Yep! I tried to improve this in a subtle way, by correcting "relevant caches are cleared" to "relevant cache entries are cleared".

We can adjust it more -- my goal is to be both precise and concise. 😁

- Note "cache entries" rather than "caches", thereby capturing that
  eviction from an LRU cache covers the GC issue for cache/lru_cache

- Add a note on hashability, next to the note about weakref. This
  provides a forum for explaining that `id()` is used and what the
  implications of that choice are.
@bedevere-app bedevere-app Bot added the type-feature A feature request or enhancement label Nov 7, 2026
@sirosen

sirosen commented Nov 7, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review! I added a doc note about hashability, which explains that

  • instances don't need to be hashable
  • distinct instances get distinct caches, even if they hash equal

I'm not sure what, if anything, to add about two of these noted cases:

  1. attribute change

    e1.symbol = 'ALPB'
    print(e1.opening_price, date(2020, 2, 20))  # ? Detect attribute change

    The answer is that there is no detection. I think this might be surprising if someone is expecting the implementation to use hash() rather than id(). Does it need some special call-out now that the use of id() is documented?

  2. cleanup timing

    del e1                                      # ? Immediate clear

    It is documented as being tied to weakref, so the immediacy of the cache-clear is based on the immediacy of GC when del is called. I think this is considered an implementation detail of CPython? But it is in practice immediate.

@johnslavik
johnslavik self-requested a review November 7, 2026 23:45

@johnslavik johnslavik left a comment •

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.

Thanks!

I'm mostly worried about the open questions on interactions with @classmethod/@staticmethod/@property.

Comment thread Lib/functools.py Resolved
Comment thread Lib/functools.py Resolved
Comment thread Doc/library/functools.rst

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.

Comment thread Lib/functools.py Resolved
Comment thread Lib/functools.py Resolved
Comment thread Lib/functools.py Resolved
Comment thread Lib/functools.py Outdated
Comment on lines +1162 to +1165
def __get__(self, instance, owner=None):
if instance is None:
return self
return self._get_or_create_cached_func(instance)

@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.

Instances can be temporary, we need to keep the ref alive here:

from functools import cached_method

class C:
   def __init__(self, x):
       self.x = x

   @cached_method
   def value(self):
       return self.x

C(10).value()
# AttributeError: 'NoneType' object has no attribute 'x'

The same problem affects saved callbacks:

c = C(10)
callback = c.value
del c
callback()  # kaboom

My idea is to create a bound method object here in __get__ and return that.

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 idea is to create a bound method object here in __get__ and return that.

I like this idea. I'll give it a try. And I think we can make one or both of the above failure cases into unit tests.

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 need to take more time to test it and think about it, but initial results seem good with this patch:

     def __get__(self, instance, owner=None):
         if instance is None:
             return self
-        return self._get_or_create_cached_func(instance)
+        unbound_func = self._get_or_create_cached_func(instance)
+
+        @wraps(unbound_func)
+        def bound_func(self, *args, **kwargs):
+            return unbound_func(*args, **kwargs)
+
+        return MethodType(bound_func, instance)

I find it somewhat disappointing that this means reconstructing a bound method on every call though.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

You could create an instance of a callable class instead of using a real bound method.

Something along the lines of:

class _bound_cached_method:
    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)

This does have the benefit of having a __repr__ that indicates that it's a cached method and also provides access to the cache_ methods of the underlying lru_cache without needing to dig around in __wrapped__.

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 like the addition of a useful repr. I also added one to the descriptor itself, as <unbound cached method {self.func.__qualname__}>. That results in a nice symmetry.
I took @DavidCEllis' version above pretty much verbatim.

Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>
@github-actions github-actions Bot removed the stale Stale PR or inactive for long period of time. label Nov 10, 2026
sirosen and others added 3 commits November 12, 2026 15:36
A specialized "_bound_cached_method" type provides a dedicated repr, and
resolves the issue noted in review that an instance could be released by
GC before the cached method has been called.

Co-authored-by: David Ellis <15880420+DavidCEllis@users.noreply.github.com>
Declare how it stacks with `@property`, and does not stack with
classmethod or staticmethod.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting merge type-feature A feature request or enhancement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a functools.cache variant for methods to avoid keeping instances alive

9 participants