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 of RuntimeError.

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 to False.

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 than sys.maxsize.

  • callback (callable or None) – Callback object to be applied to displaced or “evicted” key-value pairs.

Raises

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
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 to None 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.

Parameters

key (hashable) – Hashable object.

Returns

None.

Raises

KeyError – if key is not found.

LRUDict.__contains__(self, key, /) → Bool

Test key membership. Implement the key in L or key not in L syntax.

Parameters

key (hashable) – Hashable object.

Returns

True or False.

LRUDict.__len__(self, /) → int

Support for the builtin len() function.

Returns

The length of the LRUDict object (number of items stored).

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 the LRUDict, return the value associated with key and increment the “hits” counter, if key is in the object. Otherwise, return the value of default and increment the “missing” counter.

LRUDict.setdefault(self, key, default=None, /) → Any

If key is in the LRUDict, return the value associated with key and increment the “hits” counter (just like the get() method). Otherwise, return default, insert the key with the value default, and return default.

Note

Like Python’s dict.setdefault(), the hash function for key is evaluated only once.

LRUDict.pop(self, key, [default, ]/) → Any

If key is in the LRUDict, return its associated value, remove this (key, value) pair, and increment the “hits” counter. If key is not in the object, return default if it is given as an argument; however, if default is not given, raises KeyError. No matter whether default is given, the “missing” counter is incremented as long as key is not in the LRUDict.

Returns

(key, value) pair.

Raises

KeyError – if key is not stored but default 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), raise KeyError.

By default, The item popped is the most-recently used (MRU) one. If the optional paramter least_recent is True, 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 to LRUDict and not present for dict. It bears some similarity to Python’s collections.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 Python dict, 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 of other (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 modifying other or self while self 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 as self’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, if L in the following snippet is a LRUDict 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 the LRUDict is empty. The hits/misses counters are not modified.

Returns

(key, value) pair.

Raises

KeyError – if the LRUDict is empty.

LRUDict.peek_last_item(self, /) → Tuple[Object, Object]

Return a tuple (key, value) of the least-recently used (“last”) item, or raise KeyError if the LRUDict is empty. The hits/misses counters are not modified.

Returns

(key, value) pair.

Raises

KeyError – if the LRUDict is empty.

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 of tuple), similar to named-tuple classes created by Python collections.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

LRUDict.__repr__(self, /) → str

Return a textual representation of the LRUDict object. The output includes a preview of the stored key and values if the overall line is not too long, but the order of keys should not be presumed to be relevant.

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 to False 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 raise LRUDictBusyError.

2.3.7. Obsolete methods

LRUDict.get_size(self, /) → int
LRUDict.set_size(self, size : int, /) → None

Deprecated. Use the property size instead.

LRUDict.set_callback(self, func : Callable, /) → None

Deprecated. Use the property callback instead.