BackDict

类私有源码

bdict = BackDict[K, V](
    data: Mapping[K, V],
    back_dict: Mapping[K2, V] | Callable[[], Mapping[K2, V]],
    key_mapper: Callable[[K], K2],
    key_back_mapper: Callable[[K2], K],
)

有备用层级的字典。

作为一个两级的链式映射，其支持以下特性：

1. 第一级data是可读写域。对此字典的任何修改都会作用于data域。
2. 第二级back_dict是只读域。遍历或检索该字典时，首先会在data域搜索。若未找到，则会返回位于back_dict域的值。有鉴于对字典的修改只作用于data域，这个第二级域将保持不变。
3. 第二级域可以有和data域不同的关键字。用户需要提供key_mapper和它的反变换key_back_mapper来支持该功能。

备注

须知，此类型是dict的子类，亦即是说，下文里若有任何没有专门提及的方法或运算符，则其用法与dict相同。

参数

参数	类型	必选	说明
data	Mapping[K, T]		BackDict的可变数据存储区。
back_dict	Mapping[K2, T] | () -> Mapping[K2, T]		BackDict不可变的备用内部存储区。 该值可以是一个延迟加载器。所谓延迟加载器，指的是一个函数，当且仅当back_dict域内的数据首次被访问到的时候才调用。
key_mapper	(K) -> K2		当关键字未在data中搜索到时，用于将要搜索的关键字从K类型一一映射到K2。
key_back_mapper	(K2) -> K		当需要向用户展示可用的关键字时，用来将备用域中K2类型的关键字一一映射到K。

方法

copy

bdict_copy: BackDict[K, V] = bdict.copy()

创建BackDict的浅拷贝。

输出

参数	类型	说明
bdict_copy	BackDict[K, V]	针对该定制化两级字典的拷贝。

---

get

val: V | S = bdict.get(key: K, default: S = None)

从字典中获取一个值，并提供默认返回值。

输入

参数	类型	必选	说明
key	K		用于定位值的关键字。若所要搜索的值皆不存在于两级域中，则返回默认值。
default	S		用户提供的默认值。若在字典中未找到key，返回该值。

输出

参数	类型	说明
val	V | S	若找到了关键字，返回所定位的值。否则，返回默认值。

---

keys

key_iter: KeysView[BackDictView[K, V]] = bdict.keys()

BackDict(...).keys()是用来提供BackDict关键字视图的类集合对象。

输出

参数	类型	说明
key_iter	KeysView[BackDictView[K, V]]	针对该字典全部关键字的迭代器。迭代的范围也涵盖back_dict的关键字。每次迭代返回一个K类型的值。

---

values

val_iter: ValuesView[BackDictView[K, V]] = bdict.values()

BackDict(...).keys()是用来提供BackDict值视图的类集合对象。

输出

参数	类型	说明
val_iter	ValuesView[BackDictView[K, V]]	针对该字典全部值的迭代器。迭代的范围也涵盖back_dict的值。每次迭代返回一个V类型的值。

---

items

item_iter: ItemsView[BackDictView[K, V]] = bdict.items()

BackDict(...).keys()是用来提供BackDict键值对视图的类集合对象。

输出

参数	类型	说明
item_iter	ItemsView[BackDictView[K, V]]	针对该字典全部键值对的迭代器。迭代的范围也涵盖back_dict的键值对。每次迭代返回一个tuple[K, V]类型的二元组。

运算符

__len__

vlen: int = len(bdict)

获取字典的长度。

输出

参数	类型	说明
vlen	int	字典两级存储关键字的并集之中、关键字数目。

---

__contains__

flag: bool = key in bdict

检查key是否存在于字典中。

输入

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

输出

参数	类型	说明
flag	bool	若为True，则表面给定的key存在于字典中。若key不存在第一级域中、但能在第二级域检索到，该值还是为True。

---

__iter__

keys: Iterator[K] = iter(bdict)

遍历字典中的每个关键字。

输出

参数	类型	说明
keys	Iterator[K]	迭代器。每次迭代返回字典中的一个关键字。若所返回的关键字来自备用域，迭代器所返回的关键字会经过key_back_mapper的后处理。

---

__getitem__

val: V = bdict[key]

定位字典中的一个值。若关键字未找到，抛出KeyError。

输入

参数	类型	必选	说明
key	K		用来定位值的关键字。若值来自备用域，则会使用key_mapper(key)来定位值。

输出

参数	类型	说明
val	V	由key定位到的值。

---

__or__

any_dict: Mapping[K, V]
new_bdict: BackDict[K, V] = bdict | any_dict

将该BackDict与另一个字典合并。

输入

参数	类型	必选	说明
any_dict	Mapping[K, V]		要与该BackDict合并的映射。该映射需要和本字典有相同的键、值类型。

输出

参数	类型	说明
new_bdict	BackDict[K, V]	一个由当前字典bdict与any_dict合并而来的新字典。若关键字有所重合，则优选采用来自any_dict的值。

---

__ror__

any_dict: Mapping[K, V]
new_bdict: BackDict[K, V] = any_dict | bdict

将该BackDict与另一个字典合并。

备注

须知，该运算符仅在any_dict未实现__or__运算符时才会起效。否则，所合并的值由any_dict.__or__(bdict)给定。

输入

参数	类型	必选	说明
any_dict	Mapping[K, V]		要与该BackDict合并的映射。该映射需要和本字典有相同的键、值类型。

输出

参数	类型	说明
new_bdict	BackDict[K, V]	一个由当前字典bdict与any_dict合并而来的新字典。若关键字有所重合，则优选采用来自该BackDict的值。