3. Hits and misses¶
This is a summary of what constitutes a “hit” or a “miss”, for which the information is scattered around in the API Reference.
Note
In general,
a hit refers to the successful retrieval of a value associated with a given key from the
LRUDict
object itself, anda miss refers to one such attempt that fails.
An “insert”-like method typically neither hits nor misses, and neither does deleting a key-value pair (no matter whether the key exists). For instance, the index-assignment statement
L["watermelon"] = "green"
neither hits nor misses no matter what. The del
-index statement
del L["lemon"]
does not affect hit/miss stats either, even if it may fail and raise
KeyError
.
Somewhat special is the setdefault()
method that may either
“retrieve” from the LRUDict
– in the case that the given key is “in”;
or “insert” in it – in the case that there is not yet a key in it. The former
counts as a hit, because the value associated with the given key is indeed
obtained from the LRUDict
. However, the latter is not a miss, because
it is an insert-only operation: no attempt has been made to retrieve the value
associated with the given key.
Merely testing for membership using the in
/not in
operator
neither hits nor misses.
A miss is not always associated with a KeyError
. An example is the
get()
method. The statement
colour = L.get("apple", "red")
incurs a miss if the key "apple"
is not in L
, and it will not
raise KeyError
. The substitute value "red"
, though assigned to
the variable colour
, is missed by L
.
The methods popitem()
, peek_first_item()
, and
peek_last_item()
neither hit nor miss, because they do not
accept a key.
The tallying of hits/misses is orthogonal to other side effects. For example,
the pop()
is a “destructive” way to retrieve a value. It can hit
or miss, and in the case of a hit the item is removed from the
LRUDict
. The fact that a hit is scored does not imply that the item is
“still there”.
It is safe to say that a key, if hit and extant, will always be promoted to the most-recently used one, if it is not so already. The converse is not true: assigning a value to an existing key will promote the key to the most recent, but it is not considered a hit.