This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Document that @lru_cache caches based on exactly how the function arguments are specified
Type: Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, r.david.murray, rhettinger, solstag, thatiparthy
Priority: low Keywords: patch

Created on 2018-06-05 16:58 by solstag, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 9298 merged rhettinger, 2018-09-14 07:37
PR 9299 merged miss-islington, 2018-09-14 07:55
Messages (7)
msg318770 - (view) Author: Al-Scandar Solstag (solstag) Date: 2018-06-05 16:58

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.

msg318774 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2018-06-05 17:25
Agreed that this should be documented.
msg318793 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-06-06 01:07
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.
msg318822 - (view) Author: Al-Scandar Solstag (solstag) Date: 2018-06-06 13:48
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).
msg320358 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-06-24 06:24
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."
msg320422 - (view) Author: Al-Scandar Solstag (solstag) Date: 2018-06-25 13:28
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."
msg320430 - (view) Author: Srinivas Reddy Thatiparthy(శ్రీనివాస్ రెడ్డి తాటిపర్తి) (thatiparthy) * Date: 2018-06-25 17:06
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.
Date User Action Args
2022-04-11 14:59:01adminsetgithub: 77955
2018-09-14 08:14:28rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-09-14 07:55:12miss-islingtonsetpull_requests: + pull_request8728
2018-09-14 07:37:36rhettingersetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request8727
2018-06-25 17:06:31thatiparthysetnosy: + thatiparthy
messages: + msg320430
2018-06-25 13:28:07solstagsetmessages: + msg320422
2018-06-24 06:24:57rhettingersetmessages: + msg320358
2018-06-06 13:48:39solstagsetmessages: + msg318822
2018-06-06 01:07:13rhettingersetpriority: normal -> low
assignee: docs@python -> rhettinger
messages: + msg318793
2018-06-05 17:25:16r.david.murraysetnosy: + rhettinger, r.david.murray
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
messages: + msg318774

versions: + Python 3.6, Python 3.7, Python 3.8
stage: needs patch
2018-06-05 16:58:55solstagcreate