[issue33774] Improve doc of @lru_cache to avoid misuse and confusion
New submission from Al-Scandar Solstag <solstag@member.fsf.org>: Ni! It is not clear at all in the documentation of @lru_cache that the cache takes into account the exact way the function was called, not the values passed to its arguments, as one could/would expect. I mean that for function(a, b, c=3) the three calls below are not considered equivalent as far as the cache is concerned: function(1, 2, 3) function(1, 2, c=3) function(1, 2) I hope this can be clarified in the documentation. I wasted a great deal of time today trying to understand why my calls were not getting cached and only figured it out when I decided to go read @lru_cache's code. It seems very likely that other people have had the same problem. Or worse, people might be using @lru_cache believing it is working when it isn't. Cheers! ---------- assignee: docs@python components: Documentation messages: 318770 nosy: docs@python, solstag priority: normal severity: normal status: open title: Improve doc of @lru_cache to avoid misuse and confusion _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue33774> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: Agreed that this should be documented. ---------- nosy: +r.david.murray, rhettinger stage: -> needs patch title: Improve doc of @lru_cache to avoid misuse and confusion -> Document that @lru_cache caches based on exactly how the function arguments are specified versions: +Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue33774> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: Sure, I can add a line mentioning that distinct argument patterns may be considered as distinct cache entries even though they otherwise seem to be equivalent calls. That will just be a general statement though. The specific details are implementation dependent, have changed over time, and may change again in the future. ---------- assignee: docs@python -> rhettinger priority: normal -> low _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue33774> _______________________________________
Al-Scandar Solstag <solstag@member.fsf.org> added the comment: Hi Raymond, I think I understand what you mean, and would suggest something along the lines of: """ Note that lru_cache only guarantees cache matches on the exact way function arguments are specified, so the following ways of calling 'def f(a, b=7)' are not guaranteed to cache each other: f(1), f(a=1), f(1, 7), f(1, b=7), f(a=1, b=7). """ ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue33774> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: I propose this, "Distinct argument patterns may be considered to be distinct calls with distinct results even if the underlying function sees them as equivalent calls." ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue33774> _______________________________________
Al-Scandar Solstag <solstag@member.fsf.org> added the comment: Speaking frankly, I might not have grasped what might happen by reading your line. I think having at least a minimal example is crucial. Perhaps: "Distinct argument patterns, such as `f(1)` and `f(first_arg=1)`, may not cache for each other even if the underlying function sees them as equivalent calls." ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue33774> _______________________________________
Srinivas Reddy T <thatiparthysreenivas@gmail.com> added the comment: Hi Raymond, I find your statement hard to understand.I agree with Solstag, it is always helpful to have an example. +1 for solstag wording. ---------- nosy: +thatiparthy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue33774> _______________________________________
Change by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- keywords: +patch pull_requests: +8727 stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue33774> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +8728 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue33774> _______________________________________
Change by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue33774> _______________________________________
participants (5)
-
Al-Scandar Solstag -
miss-islington
-
R. David Murray
-
Raymond Hettinger
-
Srinivas Reddy T