2. API Reference¶
2.1. Module¶
The module lru_ng
exposes the following class, LRUDict
. It can
be imported as
from lru_ng import LRUDict
2.2. Exception¶
-
exception
lru_ng.
LRUDictBusyError
¶ Raised by any
LRUDict
method indicating the method call cannot begin because another method has not finished processing. This is a subclass ofRuntimeError
.This is typically a result of unsynchronized access in threaded code (see the section Thread safety). In single-thread code, it may arise because a key’s
__hash__()
or__eq__()
methods cause a jump while in the middle of a method call.This exception will not be raised if
LRUDict._detect_conflict
is set toFalse
.
2.3. The LRUDict
object¶
-
class
lru_ng.
LRUDict
(size: int, callback: Optional[Callable] = None)¶ Initialize a
LRUDict
object.- Parameters
size (int) – Size bound or “capacity” of the
LRUDict
object. Must be a positive integer that is no greater thansys.maxsize
.callback (callable or
None
) – Callback object to be applied to displaced or “evicted” key-value pairs.
- Raises
TypeError – if argument types do not match the intended ones.
ValueError – if
size
is negative or zero.OverflowError – if
size
is greater thansys.maxsize
.
2.3.1. Properties¶
-
property
LRUDict.
size
¶ Get or set the size bound. This property can be set (i.e. assigned to) in order to resize the bound after initialization. If the size is reduced and is less than the current length (i.e. number of items stored), evictions will be triggred.
- Raises
TypeError – if setting the size with a value that cannot be converted to integer.
ValueError – if setting the size to a negative value or zero.
OverflowError – if setting the size to a value greater than
sys.maxsize
.AttributeError – if attempting to delete the property.
-
property
LRUDict.
callback
¶ Get or set the callback. This property can be set (i.e. assigned to) in order to change the callback after initialization. The value
None
indicates that no callback is set, and setting it toNone
disables callback upon eviction.- Raises
TypeError – if setting the callback to a non-callable object.
AttributeError – if attempting to delete the property.
2.3.2. Special methods for the mapping protocol¶
-
LRUDict.
__getitem__
(self, key, /) → Any¶ Access the value associated with the key. Implement the indexing syntax
L[key]
. On success, it also increases the hits counter and increases the misses counter on failure.- Parameters
key (hashable) – Hashable object.
- Returns
The value associated with
key
.- Raises
KeyError – if
key
is not found.
-
LRUDict.
__setitem__
(self, key, value, /) → None¶ Assign the value associated with the key. Implement the index-assignment syntax
L[key] = value
. Do not modify the hit/miss counter.- Parameters
key (hashable) – Hashable object.
value – Object as value to be associated with
key
.
- Returns
None
.
-
LRUDict.
__delitem__
(self, key, /) → None¶ Delete the key and its associated value. Implement the
del L[key]
syntax. Do not modify the hit/miss counter.
-
LRUDict.
__contains__
(self, key, /) → Bool¶ Test key membership. Implement the
key in L
orkey not in L
syntax.
2.3.3. Methods emulating dict
¶
-
LRUDict.
clear
(self, /) → None¶ Remove all items from the
LRUDict
object and reset the hits/misses counter.- Returns
None
.
-
LRUDict.
get
(self, key, default=None, /) → Any¶ If
key
is in theLRUDict
, return the value associated withkey
and increment the “hits” counter, ifkey
is in the object. Otherwise, return the value ofdefault
and increment the “missing” counter.
-
LRUDict.
setdefault
(self, key, default=None, /) → Any¶ If
key
is in theLRUDict
, return the value associated withkey
and increment the “hits” counter (just like theget()
method). Otherwise, returndefault
, insert thekey
with the valuedefault
, and returndefault
.Note
Like Python’s
dict.setdefault()
, the hash function forkey
is evaluated only once.
-
LRUDict.
pop
(self, key, [default, ]/) → Any¶ If
key
is in theLRUDict
, return its associated value, remove this (key, value) pair, and increment the “hits” counter. Ifkey
is not in the object, returndefault
if it is given as an argument; however, ifdefault
is not given, raisesKeyError
. No matter whetherdefault
is given, the “missing” counter is incremented as long askey
is not in theLRUDict
.- Returns
(key, value) pair.
- Raises
KeyError – if
key
is not stored butdefault
is not given.
-
LRUDict.
popitem
(self, least_recent : Bool = False, /) → Tuple[Object, Object]¶ Return a pair (two-element tuple) key, value and remove it from the storage. If the
LRUDict
object is empty (hence no item to pop), raiseKeyError
.By default, The item popped is the most-recently used (MRU) one. If the optional paramter
least_recent
isTrue
, the least-recently used (LRU) one is returned instead.This method does not modify the hits/misses counters.
- Parameters
least_recent (bool) – Boolean flag indicating the order of popping. Default:
False
(popping the MRU)- Returns
(key, value) pair.
Note
The optional argument
least_recent
is specific toLRUDict
and not present fordict
. It bears some similarity to Python’scollections.OrderedDict.popitem()
, and the default order (LIFO) is the same despite different terminologies.
-
LRUDict.
update
(self, [other, ]/, *, **kwargs) → None¶ Update self with the key-value pairs from
other
, a Pythondict
, if the argument is present. If keyword arguments are also given, further update self using them. This method may cause eviction if the update would have grown the length of self beyond the size limit. The update is performed in the iteration order ofother
(which is the same as key-insertion order), and then the order of keyword arguments as they are specified in the method call if any.Warning
This method may make multiples passes into the critical section in order to consume the sources, and while
self
is being updated the intermediate list of evicted items may grow (bound by the diffrence of source size and self size). It is preferrable to not having another thread modifyingother
orself
whileself
is being updated.
-
LRUDict.
has_key
(self, key, /) → Bool¶ Deprecated. Use
key in L
aka.__contains__()
instead.
The following methods are modelled with their counterparts of dict
,
but instead of returning a dynamic view object, they return a list,
which contains shallow copies, that reflects the state of the LRUDict
object at the time of call. The items returned are in MRU-to-LRU order.
Accessing the items in the returned sequences will not modify the ordering of
items in the original LRUDict
object.
-
LRUDict.
keys
(self, /) → List¶
-
LRUDict.
values
(self, /) → List¶
-
LRUDict.
items
(self, /) → List[Tuple[Object, Object]]¶
2.3.4. Methods specific to LRUDict
¶
-
LRUDict.
to_dict
(self, /) → Dict¶ Return a new dictionary,
other
, whose keys and values are shallow copies of self’s.other
’s iteration order (i.e. key-insertion order) is the same asself
’s recent-use (i.e. LRU-to-MRU) order.The method can be loosely considered an inverse of
update()
when evictions are ignored. In other words, ifL
in the following snippet is aLRUDict
object,L_dup
will be it’s duplicate with the same recent-use order:d = L.to_dict() L_dup = LRUDict(len(d)) L_dup.update(d)
This can be used to dump a picklable copy if the keys and values are picklable. The pickle can be loaded into a dictionary and be used to update an empty
LRUDict
object with sufficient size to restore the original content and order.- Returns
New dictionary.
-
LRUDict.
peek_first_item
(self, /) → Tuple[Object, Object]¶ Return a tuple (key, value) of the most-recently used (“first”) item, or raise
KeyError
if theLRUDict
is empty. The hits/misses counters are not modified.
-
LRUDict.
peek_last_item
(self, /) → Tuple[Object, Object]¶ Return a tuple (key, value) of the least-recently used (“last”) item, or raise
KeyError
if theLRUDict
is empty. The hits/misses counters are not modified.
-
LRUDict.
get_stats
(self, /) → Tuple[int, int]¶ Return a tuple of integers, (hits, misses), that provides feedback on the
LRUDict
hit/miss information.Note
On CPython >= 3.8, The specific type of the return value (named
LRUDictStats
) is a built-in “struct sequence” (a subclass oftuple
), similar to named-tuple classes created by Pythoncollections.namedtuple()
. As such, it also supports accessing the fields by the attributes.hits
and.misses
respectively.Warning
The numerical values are stored as C
unsigned long
internally and may wrap around to zero if overflown, although this seems unlikely.
2.3.5. Other special methods¶
2.3.6. Less-common and experimental methods¶
-
LRUDict.
purge
(self, /) → int¶ Purge internally-buffered evicted items manually.
As an implementation detail, evicted items are temporarily buffered in the case that a callback is set when the items are evicted. Purging refers to clearing the buffer (with callback application if set). Normally, this happens without intervention, but in threaded environments there is no absolute guarantee that the buffer will always be cleared all the time. This method can be used to purge manually. As noted in Caveats with callbacks, the purge will ignore the return value of the callback and suppress exceptions raised in there.
- Returns
Number of items purged, or -1 in the case of error.
-
property
LRUDict.
_suspend_purge
¶ Set to
True
to disable purging altogether. Set toFalse
to re-enable (but do not immediately trigger purging).
-
property
LRUDict.
_purge_queue_size
¶ Peek the length of the purge buffer. The value is indicative only and may not be accurate in a threaded environment.
-
property
LRUDict.
_max_pending_callbacks
¶ The maximum number of callbacks allowed to be pending on the purge queue. Must be an integer between 1 and C
USHRT_MAX
(typically 65535).
-
property
LRUDict.
_detect_conflict
¶ Set to
False
to disable runtime conflict detection. By doing so, no method will raiseLRUDictBusyError
.