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!

Agreed that this should be documented.

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.

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).
"""

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."

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."

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.

versions: + Python 3.6, Python 3.7, Python 3.8
stage: needs patch