Documentation

Currentlythe 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 useself 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.

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

Specific proposals:

1. Thecached_property documentation should not recommend usingfunctools.cache on a method.
2. It also doesn't need to give a full example of usinglru_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