LRUDict

类源码

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
)

由最久未使用（least recently used, LRU）缓存驱动的字典，其中K, T均是泛型。

容量限定，当缓存字典填满时，检查最久未查询过的关键字，并清出该数据。

LRUDict同时是保证线程安全的。

该LRUDict在默认情况下，不会隐式地释放缓冲区内的数据。要确保数据从内存中删除，需要显示地调用pop()方法，并针对返回值进行删除。

参数

参数	类型	必选	说明
data	{K: T} | [(K, T)]		用来创建字典的数据。
**kwargs	T		在关键字参数中指定的，用来创建字典的数据。
maxsize	int		缓存最多可容纳的数据条目数（即缓存容量）。

提示

注意，该字典的初始化用法与Python标准库中dict()完全一致。

方法

clear

ldict.clear()

移除字典中的所有元素。

---

copy

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

返回原字典的浅拷贝。

---

fromkeys

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

使用来自可遍历对象的关键字iterable创建一个新LRU缓存字典，并将键值设为value。

输入

参数	类型	必选	说明
iterable	Iterable[str]		可遍历对象，用来为新创建的字典提供关键字。
value	T		共同值，新创建字典的所有关键字都赋以该值。
maxsize	int		缓存的容量。

输出

参数	类型	说明
new_ldict	LRUDict[str, T]	新初始化的LRU缓存字典，其中，关键字提供自iterable，且所有值均设置为value。

---

get

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

如果key存在于字典中则返回key的值，否则返回default。 如果default未给出则默认为None，因而此方法绝不会抛出KeyError。

输入

参数	类型	必选	说明
key	K		用来查询的关键字。
default	S		当关键字未找到时，返回的默认值。

输出

参数	类型	说明
value	T | S	查询到的值，或由default=...指定的值。

---

setdefault

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

如果字典存在关键字key，返回它的值。如果不存在，插入值为default的关键字key，并返回default。default默认为None。

输入

参数	类型	必选	说明
key	K		用来查询的关键字。
default	S		当关键字未找到时，返回的默认值。

输出

参数	类型	说明
value	T | S	查询到的值，或由default=...指定的值。

---

pop

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

如果key存在于字典中则将其移除并返回其值，否则返回default。 如果default未给出且key不存在于字典中，则会抛出KeyError。

输入

参数	类型	必选	说明
key	K		用来查询的关键字。
default	S		当关键字未找到时，返回的默认值。

输出

参数	类型	说明
value	T | S	查询到的值，或由default=...指定的值。

---

popitem

key, value = ldict.popitem()

从字典中移除并返回一个（关键字，值）对。 键值对会按后进先出的顺序被返回。

popitem()适用于对字典进行消耗性的迭代，这在集合算法中经常被使用。 如果字典为空，调用popitem()将抛出KeyError。

输出

参数	类型	说明
key	K	所返回键值对的关键字。
value	T	所返回键值对的值。

---

recent_popitem

key, value = ldict.recent_popitem()

与popitem()相同。

输出

参数	类型	说明
key	K	所返回键值对的关键字。
value	T	所返回键值对的值。

---

eldest_popitem

key, value = ldict.eldest_popitem()

运行popitem()但弹出的是最久未使用的键值对（先进先出）。

输出

参数	类型	说明
key	K	所返回键值对的关键字。
value	T	所返回键值对的值。

---

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)

使用来自data的键/值对更新字典，覆盖原有的关键字。 返回None。

update()可接收一个实现了keys()方法的对象（且，每次取得该方法返回的key，该关键字都会传递到__getitem__()）。亦可接收一个可遍历对象，其中每次遍历取得的是一个键值对（例如，每次遍历返回两个值的元组、或其他可遍历对象）。设若指定了关键字参数，则字典随后会按照、形如接下来例子的键值对参数得到更新：ldict.update(red=1, blue=2).

输入

参数	类型	必选	说明
data	{K: T} | [(K, T)]		用来更新字典的数据。
**kwargs	T		用来更新字典的、由关键字参数指定的数据。

---

keys

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

LRUDict(...).keys()是一个有序类集合对象，用来提供LRUDict的关键字视图。

输出

参数	类型	说明
keys	Iterator[K]	针对所有关键字的有序迭代器。

---

values

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

LRUDict(...).values()是一个有序类集合对象，用来提供LRUDict的值视图。

输出

参数	类型	说明
values	Iterator[T]	针对所有值的有序迭代器。

---

items

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

LRUDict(...).items()是一个有序类集合对象，用来提供LRUDict的键值对视图。

输出

参数	类型	说明
items	Iterator[Tuple[K, T]]	针对所有字典项的有序迭代器。

---

reversed

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

返回字典关键字的逆向迭代器。该方法是reversed(LRUDict.keys())的简写。

输出

参数	类型	说明
rev_keys	Iterator[K]	针对所有关键字的逆向有序迭代器。

---

move_to_recent

ldict.move_to_recent(key: K)

将某个特定的关键字，移动到LRUDict最近的位置。

输入

参数	类型	必选	说明
key	K		所移动的字典项的关键字，该方法将其标记为最近使用的字典项。

---

index

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

给定关键字，返回该关键字在LRUDict中的优先级排序下标。

调用该方法不会影响关键字在字典中的顺序。

输入

参数	类型	必选	说明
key	K		用来查询字典项下标的关键字。

输出

参数	类型	说明
idx	int	所查询到的字典项的下标。该下标值越小，则表示该字典项越近。

---

back_index

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

给定优先级下标，获取该下标在LRUDict对应的关键字。

调用该方法不会影响关键字在字典中的顺序。

输入

参数	类型	必选	说明
idx	int		用来查询关键字的字典项下标。

输出

参数	类型	说明
key	K	透过idx查询到的字典项关键字。

---

reverse

ldict.reverse()

翻转LRUDict中各关键字的优先级顺序。

---

rotate

ldict.rotate(n: int)

向低优先级的方向，将LRUDict的关键字循环移动n步。若n取负值，则向高优先级的方向移动。

输入

参数	类型	必选	说明
n	int		向低优先级方向循环移动的步数。

属性

maxsize

maxsize: int = ldict.maxsize

LRU 字典缓存的容量（最大尺寸）。

---

is_full

is_full: bool = ldict.is_full

字典ldict是否填满。

---

recent

key: K = ldict.recent

最近字典项的关键字。

---

eldest

key: K = ldict.eldest

最久未使用字典项的关键字。换言之，若ldict填满，则向字典添加新值的行为、会导致该字典项从字典清出。

---

recent_val

value: T = ldict.recent_val

最近字典项的值。

---

eldest_val

value: T = ldict.eldest_val

最久未使用字典项的值。换言之，若ldict填满，则向字典添加新值的行为、会导致该字典项从字典清出。

---

recent_item

key, value = ldict.recent_item

最近的字典项（键值对）。

---

eldest_item

key, value = ldict.eldest_item

最久未使用字典项（键值对(key, val)）。换言之，若ldict填满，则向字典添加新值的行为、会导致该字典项从字典清出。

运算符

__len__

dict_len: int = len(ldict)

返回字典ldict中包含的字典项数目。

输出

参数	类型	说明
dict_len	int	字典所含的字典项数目。

---

__contains__

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

若ldict含有关键字key，返回True，否则返回False。

输入

参数	类型	必选	说明
key	K		要验证的关键字。

输出

参数	类型	说明
flag	bool	若该值为 True，则表明给定的关键字key存在于字典中。

---

__getitem__

value: T = ldict[key]

返回ldict中以key为关键字的项。 若映射中不存在key，则会抛出KeyError。注意，调用该方法会将所查询的字典项标记为最近。

输入

参数	类型	必选	说明
key	K		用来查询值的关键字。

输出

参数	类型	说明
value	T	由key查询到的值。

---

__setitem__

value: T
ldict[key] = value

将ldict[key]设置为value。注意，调用该方法会将所查询的字典项标记为最近。

输入

参数	类型	必选	说明
key	K		用来查询、要设置的值、所对应的关键字。
value	T		用来设置于字典中的值。

---

__delitem__

del ldict[key]

从ldict移除ldict[key]。若关键字key不存在于字典中，抛出KeyError。

输入

参数	类型	必选	说明
key	K		用来查询、要移除的字典项，所对应的关键字。

---

__iter__

for key in ldict:
    key: K

将字典的所有关键字返回为有序迭代器。该运算符是iter(ldict.keys())的简写。

---

__or__

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

将该LRUDict和另一个字典other_dict、所有的键值对合成为一个新的LRUDict。此处“另一个字典”可以是任何映射类型的实例。当某关键字同时出现于两个字典中时，位于other_dict的值具有更高的优先级。

输入

参数	类型	必选	说明
other_dict	Mapping[K, T]		用来覆盖ldict值得另一个字典。

输出

参数	类型	说明
new_ldict	LRUDict[K, T]	新的LRUDict，由ldict和other_dict合成。

---

__ror__

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

将该LRUDict和另一个字典other_dict、所有的键值对合成为一个新的LRUDict。此处“另一个字典”可以是任何映射类型的实例。当某关键字同时出现于两个字典中时，位于LRUDict的值具有更高的优先级。

注意该方法只会在other_dict未提供__or__运算符得情况下起使用。

输入

参数	类型	必选	说明
other_dict	Mapping[K, T]		用来扩增ldict的另一个字典。

输出

参数	类型	说明
new_ldict	LRUDict[K, T]	新的LRUDict，由other_dict和ldict合成。

---

__ior__

ldict |= other_dict

将另一个字典或键值对other_dict更新到LRUDict中。当某关键字同时出现于两个字典中时，位于other_dict的值具有更高的优先级。

输入

参数	类型	必选	说明
other_dict	Mapping[K, T]		用来修改和覆盖ldict值的另一个字典。