we should not recommend using functools.cache on methods

[carljm]

Documentation

Currently the documentation for functools.cached_property recommends stacking @property and @functools.cache decorators to "achieve an effect similar to" functools.cached_property. But this omits a critical problem with using @functools.cache on instance methods: it is an unbounded cache, and will use self as a cache key, so any instance on which this "cached property" is ever accessed will be kept alive by the cache forever (unless the cache is manually cleared), and the memory used by these cached instances can grow unboundedly.

The FAQ entry on caching methods does not recommend (or even mention) functools.cache, and it explicitly recommends a bounded functools.lru_cache in order to avoid keeping alive all instances indefinitely.

Specific proposals:

1. The cached_property documentation should not recommend using functools.cache on a method.
2. It also doesn't need to give a full example of using lru_cache for a method cache; it can instead just mention the possibility, and link to the FAQ entry for more detailed discussion.

Linked PRs

• gh-104112: link from cached_property docs to method-caching FAQ #104113
• [3.11] gh-104112: link from cached_property docs to method-caching FAQ (GH-104113) #104182

[sunmy2019]

LGTM. May backport to earlier versions?

[hauntsaninja]

Yup, we usually backport documentation fixes to maintained Python versions.

Jelle wrote up some general guidelines around backporting here: https://github.com/JelleZijlstra/JelleZijlstra.github.io/blob/main/cpython.md#backporting