[issue44310] Document that lru_cache uses hard references

[Raymond Hettinger]

Raymond Hettinger <raymond.hettinger at gmail.com> added the comment:

I'm thinking of a more minimal and targeted edit than what is in the PR.   

Per the dev guide, we usually word the docs in an affirmative and specific manner (here is what the tool does and an example of how to use it).  Recounting a specific debugging case or misassumption usually isn't worthwhile unless it is a common misconception.

For strong versus weak references, we've had no previous reports even though the lru_cache() has been around for a long time.  Likely, that is because the standard library uses strong references everywhere unless specifically documented to the contrary.  Otherwise, we would have to add a strong reference note to everything stateful object in the language.

Another reason that it likely hasn't mattered to other users is that an lru cache automatically purges old entries.  If an object is not longer used, it cycles out as new items are added to the cache.  Arguably, a key feature of an LRU algorithm is that you don't have to think about the lifetime of objects.   

I'll think it a for a while and will propose an alternate edit that focuses on how the cache works with methods.  The essential point is that the instance is included in the cache key (which is usually what people want).  Discussing weak vs strong references is likely just a distractor.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue44310>
_______________________________________