LRUDict

ClassSource

ldict = LRUDict(maxsize: int = 10)
ldict: LRUDict[str, T] = LRUDict(**kwargs: T, maxsize: int = 10)
ldict: LRUDict[K, T] = LRUDict(data={k1: ..., k2: ...}, maxsize: int = 10)
ldict: Mapping[str, T] = LRUDict(
    data={"key1": ..., "key2": ...}, **kwargs: T, maxsize: int = 10
)
ldict: Mapping[K, T] = LRUDict(
    data=((key, val) for (key, val) in ...), maxsize: int = 10
)
ldict: Mapping[str, T] = LRUDict(
    data=((key, val) for (key, val) in ...), **kwargs, maxsize: int = 10
)

The dictionary powered by the least recently used cache, where K, T are generic types.

Limit size, evicting the least recently looked-up key when full.

This LRUDict is also ensured to be thread-safe.

This LRUDict would not allow the implicit releasing of the buffer by default. Users need to use pop() method and delete the popped object to release the buffer explictly.

Arguments

Argument	Type	Required	Description
data	{K: T} | [(K, T)]		The data used for creating the dictionary.
**kwargs	T		The data specified in the keyword arguments and used for creating the dictionary.
maxsize	int		The maximum of items (size) of the cache.

tip

Note that the initialization of this dictionary is totally the same as dict() in Python STL.

Methods

clear

ldict.clear()

Remove all items from the dictionary.

---

copy

new_ldict: LRUDict[K, T] = ldict.copy()

Return a shallow copy of the dictionary.

---

fromkeys

new_ldict: LRUDict[str, T] = LRUDict.fromkeys(
    iterable: Iterable[str], value: T | None = None, maxsize: int = 10
)

Create a new LRU-cached dictionary with keys from iterable and values set to value.

Requires

Argument	Type	Required	Description
iterable	Iterable[str]		An iterable object that will be used as the key values of the newly created dictionary.
value	T		The value that will be assigned to all keywords in the created dictionary.
maxsize	int		The size of the cache.

Returns

Argument	Type	Description
new_ldict	LRUDict[str, T]	The newly initialized LRU-cache dictionary, where the key values are provided by iterable and all values are specified as value.

---

get

value: T | None = ldict.get(key: K)
value: T | S = ldict.get(key: K, default: S)

Return the value for key if key is in the dictionary, else default. If default is not given, it defaults to None, so that this method never raises a KeyError.

Requires

Argument	Type	Required	Description
key	K		The keyword to be queried.
default	S		The default value that is used when key is not found in the dictionary.

Returns

Argument	Type	Description
value	T | S	The queried value or the value specified by default=....

---

setdefault

value: T | None = ldict.setdefault(key: K)
value: T | S = ldict.setdefault(key: K, default: S)

If key is in the dictionary, return its value. If not, insert key with a value of default and return default. default defaults to None.

Requires

Argument	Type	Required	Description
key	K		The keyword to be queried.
default	S		The default value that is used when key is not found in the dictionary.

Returns

Argument	Type	Description
value	T | S	The queried value or the value specified by default=....

---

pop

value: T = ldict.pop(key: K)
value: T | S = ldict.pop(key: K, default: S)

If key is in the dictionary, remove it and return its value, else return default. If default is not given and key is not in the dictionary, a KeyError is raised.

Requires

Argument	Type	Required	Description
key	K		The keyword to be queried.
default	S		The default value that is used when key is not found in the dictionary.

Returns

Argument	Type	Description
value	T | S	The removed value specified by key or the value specified by default=....

---

popitem

key, value = ldict.popitem()

Remove and return a (key, value) pair from the dictionary. Pairs are returned in LIFO order.

popitem() is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, calling popitem() raises a KeyError.

Returns

Argument	Type	Description
key	K	The keyword of the returned and removed item.
value	T	The value of the returned and removed item.

---

recent_popitem

key, value = ldict.recent_popitem()

The same as popitem().

Returns

Argument	Type	Description
key	K	The keyword of the returned and removed item.
value	T	The value of the returned and removed item.

---

eldest_popitem

key, value = ldict.eldest_popitem()

Run popitem() but pop the eldest item.

Returns

Argument	Type	Description
key	K	The keyword of the returned and removed item.
value	T	The value of the returned and removed item.

---

update

ldict.update(data, /, **kwargs: T)
ldict.update(data={k1: ..., k2: ...}, /)
ldict.update(data={"key1": ..., "key2": ...}, /, **kwargs: T)
ldict.update(data=((key, val) for (key, val) in ...), /)
ldict.update(data=((key, val) for (key, val) in ...), /, **kwargs: T)

Update the dictionary with the key/value pairs from data, overwriting existing keys. Return None.

update() accepts either another object with a keys() method (in which case __getitem__() is called with every key returned from the method). or an iterable of key/value pairs (as tuples or other iterables of length two). If keyword arguments are specified, the dictionary is then updated with those key/value pairs: ldict.update(red=1, blue=2).

Requires

Argument	Type	Required	Description
data	{K: T} | [(K, T)]		The data used for updating the dictionary.
**kwargs	T		The data specified in the keyword arguments and used for updating the dictionary.

---

keys

keys: Iterator[K] = ldict.keys()

LRUDict(...).keys() is an ordered set-like object providing a view on LRUDict's keys.

Returns

Argument	Type	Description
keys	Iterator[K]	The iterator of all ordered keywords.

---

values

values: Iterator[T] = ldict.values()

LRUDict(...).values() is an ordered set-like object providing a view on LRUDict's values.

Returns

Argument	Type	Description
values	Iterator[T]	The iterator of all ordered values.

---

items

items: Iterator[Tuple[K, T]] = ldict.items()

LRUDict(...).items() is an ordered set-like object providing a view on LRUDict's items.

Returns

Argument	Type	Description
items	Iterator[Tuple[K, T]]	The iterator of all ordered dictionary items.

---

reversed

rev_keys: Iterator[K] = ldict.reversed()

Return a reverse iterator over the keys of the dictionary. This is a shortcut for reversed(LRUDict.keys()).

Returns

Argument	Type	Description
rev_keys	Iterator[K]	The iterator of all keywords in the reversed order.

---

move_to_recent

ldict.move_to_recent(key: K)

Move a specific key to the most recent place of the LRUDict.

Requires

Argument	Type	Required	Description
key	K		The keyword of the item that will be marked as the recent item by this method.

---

index

idx: int = ldict.index(key: K)

Given the keyword, return the priority index of this keyword in the LRUDict.

This method will not influence the order of keys.

Requires

Argument	Type	Required	Description
key	K		The keyword of the item index that will be queried.

Returns

Argument	Type	Description
idx	int	The index of the queried item. A smaller value represents a more recent item.

---

back_index

key: K = ldict.index(idx: int)

Given the priority index, get the corresponding keyword in the LRUDict.

This method will not influence the order of keys.

Requires

Argument	Type	Required	Description
idx	int		The index of the item to be queried.

Returns

Argument	Type	Description
key	K	The keyword of the item queried by idx.

---

reverse

ldict.reverse()

Revert the priority order of keys in this LRUDict.

---

rotate

ldict.rotate(n: int)

Rotate the priority order of keys in this LRUDict by n steps to the lower priority direction. If n is negative, rotate to the higher priority direction.

Requires

Argument	Type	Required	Description
n	int		The number of steps for rotating to the lower priority direction.

Properties

maxsize

maxsize: int = ldict.maxsize

The maximal size of the LRU dictionary cache.

---

is_full

is_full: bool = ldict.is_full

Whether the ldict is full.

---

recent

key: K = ldict.recent

Get the keyword of the recent item.

---

eldest

key: K = ldict.eldest

Get the keyword of the eldest item, i.e. the item to be removed if the ldict is full and the new value arrives.

---

recent_val

value: T = ldict.recent_val

Get the value of the recent item.

---

eldest_val

value: T = ldict.eldest_val

Get the value of the eldest item, i.e. the item to be removed if the ldict is full and the new value arrives.

---

recent_item

key, value = ldict.recent_item

Get the recent (key, val) item.

---

eldest_item

key, value = ldict.eldest_item

Get the eldest (key, val) item, i.e. the item to be removed if the ldict is full and the new value arrives.

Operators

__len__

dict_len: int = len(ldict)

Return the number of items in the dictionary ldict.

Returns

Argument	Type	Description
dict_len	int	The number of items in the dictionary.

---

__contains__

flag: bool = key in ldict
inv_flag: bool = key not in ldict

Return True if ldict has a key key, else False.

Requires

Argument	Type	Required	Description
key	K		The keyword to be validated.

Returns

Argument	Type	Description
flag	bool	If True, the given key value exists in the dictionary.

---

__getitem__

value: T = ldict[key]

Return the item of ldict with key key. Raises a KeyError if key is not in the map. Note that this method will cause the queried item marked as the recent one.

Requires

Argument	Type	Required	Description
key	K		The keyword used for quering the value.

Returns

Argument	Type	Description
value	T	The value of the queried key.

---

__setitem__

value: T
ldict[key] = value

Set ldict[key] to value. Note that this method will cause the queried item marked as the recent one.

Requires

Argument	Type	Required	Description
key	K		The keyword used for quering the value to be set.
value	T		The value to be set in the dictionary.

---

__delitem__

del ldict[key]

Remove ldict[key] from ldict. Raises a KeyError if key is not in the dictionary.

Requires

Argument	Type	Required	Description
key	K		The keyword used for quering the value to be removed.

---

__iter__

for key in ldict:
    key: K

Return an ordered iterator over the keys of the dictionary. This is a shortcut for iter(ldict.keys()).

---

__or__

new_ldict: LRUDict[K, T] = ldict | other_dict

Create a new LRUDict with the merged keys and values of this LRUDict and other_dict, which can be an arbitrary mapping type. The values of other_dict take priority when the keys are shared.

Requires

Argument	Type	Required	Description
other_dict	Mapping[K, T]		The other dictionary that will override the values in ldict.

Returns

Argument	Type	Description
new_ldict	LRUDict[K, T]	A new LRUDict merged by ldict and other_dict.

---

__ror__

new_ldict: LRUDict[K, T] = other_dict | ldict

Create a new LRUDict with the merged keys and values of this LRUDict and other_dict, which can be an arbitrary mapping type. The values of this LRUDict take priority when the keys are shared.

Note that this method is used only when other_dict does not implement the __or__ operator.

Requires

Argument	Type	Required	Description
other_dict	Mapping[K, T]		The other dictionary that will expand the values in ldict.

Returns

Argument	Type	Description
new_ldict	LRUDict[K, T]	A new LRUDict merged by other_dict and ldict.

---

__ior__

ldict |= other_dict

Update this LRUDict with keys and values from other_dict, which may be either a mapping or an iterable of key/value pairs. The values of other_dict take priority when keys are shared.

Requires

Argument	Type	Required	Description
other_dict	Mapping[K, T]		The other dictionary that will modify and override the values in ldict.