gh-102618: Introduce a `functools.cached_method` decorator by sirosen · Pull Request #150002 · python/cpython

sirosen · 2026-05-18T16:31:57Z

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 change¹ 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! 😄

Issue: Add a functools.cache variant for methods to avoid keeping instances alive #102618

at PyCon US 2026 ↩

read-the-docs-community · 2026-05-18T16:35:39Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #33694417 | 📁 Comparing a7f206c against main (1692854)

🔍 Preview build

245 files changed · + 6 added · ± 238 modified · - 1 deleted

+ Added

± Modified

- Deleted

library/asyncio-policy.html

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.

@jaraco

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 · 2026-05-18T22:56:52Z

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 · 2026-05-19T00:55:49Z

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

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.

GrahamDumpleton · 2026-05-24T03:55:20Z

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:

Co-authored-by: Edgar Ramírez Mondragón <16805946+edgarrmondragon@users.noreply.github.com>

jaraco

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

This needs a What's New in 3.16 entry.

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 · 2026-07-17T02:15:59Z

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

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

"Added in version 3.16.0a0 (unreleased)"

StanFromIreland · 2026-07-19T14:11:15Z

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


Suggested change

(Contributed by Stephen Rosen in :gh:`150002`.)

(Contributed by Stephen Rosen in :gh:`102618`.)

Issue is preferred here IIRC, right Hugo?

Is that right? That seems odd. "Contributed by X in Y" suggests to me that "Y" is the implementation (PR), not specification (issue).

StanFromIreland · 2026-07-19T14:20:38Z

+def cached_method(func=None, /, maxsize=None, typed=False):
+    if func is None:
+        def decorator(func):
+            return _cached_method(func, maxsize=maxsize, typed=typed)


lru_cache does a little dance to ensure maxsize is not junk:

cpython/Lib/functools.py

Lines 586 to 600 in 1604043

if isinstance(maxsize, int):

# Negative maxsize is treated as 0

if maxsize < 0:

maxsize = 0

elif callable(maxsize) and isinstance(typed, bool):

# The user_function was passed in directly via the maxsize argument

user_function, maxsize = maxsize, 128

wrapper = _lru_cache_wrapper(user_function, maxsize, typed, _CacheInfo)

wrapper.cache_parameters = lambda : {'maxsize': maxsize, 'typed': typed}

return update_wrapper(wrapper, user_function)

elif maxsize is not None:

raise TypeError(

'Expected first argument to be an integer, a callable, or None')

I think we should do it here too to avoid confusing errors.

It came out slightly differently in 8086aa5 because the signatures are a bit different, but the idea is the same.

cached_method is able to have a slightly better signature because it uses a positional-only param, not having the burdens of history.

StanFromIreland · 2026-07-19T14:23:10Z

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


No default, what about races?

I didn't realize, at first, that a race was possible, but I'm pretty sure it is if two concurrent writers create separate weakrefs. I'll add pop(id_key, None).
Do we want to further double-check for this kind of safety?

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.

sirosen requested a review from rhettinger as a code owner May 18, 2026 16:31

bedevere-app Bot mentioned this pull request May 18, 2026

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

Open

bedevere-app Bot added the awaiting review label May 18, 2026

sirosen force-pushed the cached-method branch from e4ba398 to a5b4b0d Compare May 18, 2026 16:39

jaraco reviewed May 18, 2026

View reviewed changes

Comment thread Lib/functools.py Outdated

jaraco reviewed May 18, 2026

View reviewed changes

Comment thread Lib/functools.py Outdated

sirosen and others added 2 commits May 18, 2026 16:51

Minor tweaks to cached_method docs

8ff6b31

- Fix doc references - Use imperative mood in a comment Co-authored-by: Jason R. Coombs <308610+jaraco@users.noreply.github.com>

DavidCEllis reviewed May 19, 2026

View reviewed changes

Comment thread Lib/functools.py Outdated

Comment thread Lib/functools.py Outdated

sirosen added 2 commits May 19, 2026 11:02

Fix signature line in docs for cached_method

9d109fa

sirosen force-pushed the cached-method branch from 75c85ce to 9d109fa Compare May 19, 2026 16:02

StanFromIreland reviewed May 19, 2026

View reviewed changes

Comment thread Doc/library/functools.rst Outdated

Fix use of a latin abbreviation

d26358a

edgarrmondragon reviewed May 28, 2026

View reviewed changes

Comment thread Doc/library/functools.rst Outdated

Update Doc/library/functools.rst

0686932

Co-authored-by: Edgar Ramírez Mondragón <16805946+edgarrmondragon@users.noreply.github.com>

jaraco approved these changes Jul 14, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting review labels Jul 14, 2026

StanFromIreland reviewed Jul 15, 2026

View reviewed changes

sirosen added 2 commits July 16, 2026 20:58

Add functools.cached_method to What's New

fffc5d3

sirosen requested a review from AA-Turner as a code owner July 17, 2026 02:11

Merge branch 'main' into cached-method

57cc653

hugovk reviewed Jul 19, 2026

View reviewed changes

Comment thread Doc/library/functools.rst Outdated

StanFromIreland reviewed Jul 19, 2026

View reviewed changes

sirosen and others added 5 commits July 21, 2026 13:55

Apply suggestions from code review

06c2b18

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Stan Ulbrych <stan@python.org>

Apply suggestion from @StanFromIreland

365c484

Co-authored-by: Stan Ulbrych <stan@python.org>

Move cached_method above cached_property

981013b

And add it to functools' `__all__` list.

Check type of 'maxsize' in cached_method

8086aa5

Fix race condition in cached_method

a7f206c

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.

	(Contributed by Stephen Rosen in :gh:`150002`.)
	(Contributed by Stephen Rosen in :gh:`102618`.)

	if isinstance(maxsize, int):
	# Negative maxsize is treated as 0
	if maxsize < 0:
	maxsize = 0

	elif callable(maxsize) and isinstance(typed, bool):
	# The user_function was passed in directly via the maxsize argument
	user_function, maxsize = maxsize, 128
	wrapper = _lru_cache_wrapper(user_function, maxsize, typed, _CacheInfo)
	wrapper.cache_parameters = lambda : {'maxsize': maxsize, 'typed': typed}
	return update_wrapper(wrapper, user_function)

	elif maxsize is not None:
	raise TypeError(
	'Expected first argument to be an integer, a callable, or None')

Uh oh!

Uh oh!

Conversation

sirosen commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Footnotes

Uh oh!

read-the-docs-community Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Uh oh!

sirosen commented May 18, 2026

Uh oh!

sirosen commented May 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GrahamDumpleton commented May 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jaraco left a comment

Choose a reason for hiding this comment

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

sirosen commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

sirosen Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

sirosen Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

StanFromIreland Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

sirosen Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

sirosen commented May 18, 2026 •

edited

Loading

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

edited

Loading

GrahamDumpleton commented May 24, 2026 •

edited

Loading

sirosen commented Jul 17, 2026 •

edited

Loading