gh-102618: Introduce a functools.cached_method decorator

[sirosen]

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"

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

Footnotes

1. at PyCon US 2026 ↩

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32748897 | 📁 Comparing 75c85ce against main (1692854)

  🔍 Preview build  

11 files changed · + 1 added · ± 10 modified

+ Added

• deprecations/pending-removal-in-3.21.html

± Modified

• deprecations/index.html
• library/dataclasses.html
• library/functools.html
• library/inspect.html
• library/os.html
• library/pathlib.html
• library/ssl.html
• whatsnew/3.15.html
• whatsnew/3.16.html
• whatsnew/changelog.html

[sirosen]

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]

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