用 bool-hybrid-array 的 BHA_Dict 存有序键值:一轮真机实测记录

为什么会去看一个字典结构

写后端和数据处理的人,跟 dict 打交道是日常:按键取值、批量更新、去重、排序遍历。Python 内置 dict 从 3.7 起保留插入顺序,日常用着很顺手;但有些场景我需要的不是“插入顺序”,而是“按键大小排好序的遍历”,这时候要么每次自己 sorted(d.items()),要么找一个底层就是有序结构的映射。一个好程序员应该知道一下这些选型里的差别,今天这篇就把 bool-hybrid-array 里的 BHA_Dict 拉出来,在本机实装版本上逐项跑一遍,记录它的构造、存取、遍历顺序、边界行为和规模表现。

大家应该都知道 bool-hybrid-array 吧?它主库是布尔数组的密集/稀疏混合存储,struct_array 子包里还带了几个基于红黑树的有序集合和映射类型。BHA_Dict 就是这个子包里的有序映射,本轮从 bool_hybrid_array.struct_array 导入。写这篇之前我先把本机版本和权威信息核过:本机 9.13.12,与 PyPI 当时 latest 一致;Python 3.12,numpy 2.5.5;许可证 Apache-2.0 OR MulanPSL-2.0 双许可,Python 要求 >=3.8,主依赖 numpy>=1.19.0。

struct_array 子包里的位置

struct_array 子包围绕结构体和有序集合组织:StructRSBTSet 是一个基于红黑树的有序集合,实现 MutableSet 协议;BHA_Dict 则在它之上包出映射语义,实现 MutableMapping 协议;同包还有一批 BHA_Struct 派生的结构体类型,比如 BHA_Point、BHA_Point3D、BHA_Rect、BHA_Version 等,以及结构体混合数组 StructHybridArray。BHA_Dict 内部在构造时会按 keytype、valuetype 动态生成一个 Pair 结构体类,名字形如 BHA_Pair_<键类型>_<值类型>,把键和值绑成一对,再放进 StructRSBTSet 里按键维护有序。

理解这个层级有助于判断什么时候用哪个:只需要一组去重且有序的键,看 StructRSBTSet;需要键值成对、按键有序遍历,用 BHA_Dict;要在混合数组里存结构化记录,再看 StructHybridArray。本轮重点记录 BHA_Dict。

本轮测量口径

这轮实测在独立冷进程里跑,脚本和输出都留了档。测试覆盖:构造方式、乱序插入后的遍历顺序、重复键覆盖、标准映射方法、键类型自动转换、不存在键的异常、空字典、copy 与相等比较、千条规模下的插入/遍历/取值耗时、浮点类型往返。耗时取当轮实测毫秒值,样本是固定随机种子生成的;换数据分布和硬件,数字只作量级参照。

构造:要先声明键和值的类型

内置 dict 不需要声明类型,键值可以混着放;BHA_Dict 不一样,构造函数要先给定 keytype 和 valuetype:

from bool_hybrid_array.struct_array import BHA_Dict

d = BHA_Dict(int, str)
d[30] = "thirty"
d[7] = "seven"

源码签名是 BHA_Dict(keytype, valuetype, items=None, **kwargs)。除了空构造,还支持传入可迭代的键值对列表,也支持关键字参数:

dk = BHA_Dict(int, str, items=[(3, "c"), (1, "a"), (2, "b")])
dkw = BHA_Dict(str, int, one=1, two=2)

本轮实测这两种构造都成立:items 列表传入后内部逐条写入;kwargs 传入的键会按字符串处理。类型上它是 MutableMapping 的子类,方法解析顺序依次是 BHA_Dict、MutableMapping、Mapping、Collection、Sized、Iterable、Container、object,也就是说映射协议要求的那几个抽象方法它都实现了,能被当成 Mapping 接口使用。

乱序插入,遍历出来是升序的

这是 BHA_Dict 最核心的一点。我故意不按大小顺序插键:30、7、1、22、15,对应值 thirty、seven、one、twenty-two、fifteen。

d = BHA_Dict(int, str)
for k, v in [(30, "thirty"), (7, "seven"), (1, "one"), (22, "twenty-two"), (15, "fifteen")]:
    d[k] = v

遍历结果:

keys:   [1, 7, 15, 22, 30]
values: ['one', 'seven', 'fifteen', 'twenty-two', 'thirty']
items:  [(1, 'one'), (7, 'seven'), (15, 'fifteen'), (22, 'twenty-two'), (30, 'thirty')]

插入顺序是 30、7、1、22、15,遍历出来却是 1、7、15、22、30,按键升序排列。本轮脚本里专门比对了 list(d.keys()) == sorted(...),结果为 True。底层是 StructRSBTSet 红黑树,键在树上保持有序,所以 keys、values、items 三个视图遍历出来的都是升序序列,而不是插入顺序。这一点和内置 dict 正好是两种语义:内置 dict 保插入顺序,要排序得另做;BHA_Dict 从结构上就保证遍历有序。

重复键:覆盖值,不新增节点

往已有键上再赋值,行为和 dict 一致:替换值,键的数量不增加。

d[7] = "SEVEN-updated"

本轮实测赋值后 d[7] 是 SEVEN-updated,len(d) 仍然是 5,没有多出一条。底层在写入时先按键查找,找到已有节点就改对应的值,不改动树结构;找不到才插入新节点。

标准映射方法逐项跑了一遍

MutableMapping 派生下来的常用方法,本轮都在同一个实例上跑过:

7 in d          # True
99 in d         # False
d.get(1)        # 'one'
d.get(99)       # None
d.get(99, "na") # 'na'
d.setdefault(5, "five")   # 新增 5 -> 'five'
d.update({100: "hundred", 2: "two"})
d.pop(22)       # 'twenty-two'

逐项结果:in 判断成员存在;get 取不到键返回 None,带默认值时返回默认值;setdefault 键不存在就写入默认值并返回,键已存在则保留原值、不取默认——本轮对已存在的 7 调 setdefault(7, "x"),返回的仍是原来的 SEVEN-updated,长度不变;update 批量并入另一组映射;pop 取出并删除指定键。

删除不存在的键会抛 KeyError。本轮 pop(222) 抛出 KeyError(222);直接用下标取不存在的键 d[999] 同样抛 KeyError(999)。这和内置 dict 的异常类型一致,接入时按 KeyError 捕获即可。

键类型会自动转换

构造时键类型被固定下来,写入时如果传入的键不是该类型,内部会尝试用 keytype 转换。本轮构造了一个 keytype=str 的字典:

ds = BHA_Dict(str, int)
ds["1"] = 10
ds[2] = 20   # 整数键经 str 转换

实测 items 是 [('1', 10), ('2', 20)];判断成员时,2 in ds 和 '2' in ds 都为 True,因为传入的整数 2 会先转成字符串再查。值类型同理由 valuetype 约束。这一点在混用数字键和字符串键时要留意:类型转换能不能成功,取决于目标类型的构造器能不能接收传入值,转换失败会在对应构造器处抛错。

空字典与构造边界

空构造的实例:len 为 0,list(d.keys()) 是空列表,布尔判断为 False。这和空 dict 的语义一致。

浮点类型往返也跑了一组:BHA_Dict(float, float) 写入 1.5、3 两个键,3 经 float 转成 3.0。读回来的键值是 BHA_Float(1.5)、BHA_Float(2.5)、BHA_Float(3.0)、BHA_Float(4.0),也就是浮点侧返回的是库内的 BHA_Float 包装类型,而不是原生 Python float;比较和取值时按包装类型的语义走,接入前最好在自己的下游消费代码里确认类型兼容。

视图与迭代的返回形式

本轮还留意了 keys、values、items 的返回形式:三个方法返回的都是生成器,按红黑树有序逐个产出,而不是一次性把全部键值拷贝成列表。需要随机下标访问或多次遍历时,先 list(...) 展开成列表即可,本轮脚本里就是这样取 keys 列表再和 sorted 结果比对的。直接迭代实例本身,等价于迭代 keys;in 判断走树查找,不是把全部键展开再比对。

这一点在大数据量下有实际意义:有序遍历是顺着树走,不需要像内置 dict 那样额外排序;但生成器只能消费一次,第二次再用要重新调 keys/values/items。如果要把同一份键值反复用,建议展开成列表留存,避免重复生成。

copy 是独立副本,相等比较与 dict 互通

dc = d.copy()
dc == d            # True
dc == dict(d.items())  # True
dc[1] = "CHANGED"
# d[1] 仍是 'one',dc[1] 变成 'CHANGED'

本轮实测:copy 出来的新字典与原字典内容相等,和内置 dict 按 items 构造的字典也相等;改副本不会影响原字典,copy 是独立副本。相等比较只要对方是 MutableMapping 且键值一一对应即成立,不要求类型必须相同。

千条规模下的耗时

为了看规模表现,本轮用固定随机种子从 1 到 100000 里抽 1000 个不重复键,逐条写入 BHA_Dict,再遍历、再取其中 100 个键:

len: 1000
插入 1000 条: 288.471 ms
遍历 keys:    1.647 ms
取 100 个键:  6.547 ms
遍历升序:     True

插入阶段耗时最高,红黑树逐条插入要维护有序结构;遍历很快,1000 条 keys 展开 1.647 毫秒;取值走树查找,100 次 6.547 毫秒。这些数字绑定本轮这台机器和这批随机键,只用来感受量级:写入偏结构化、读取和遍历偏轻量。如果业务是大量一次性批量写入、之后以遍历和查询为主,这个结构的负担主要在写入侧;如果是高频反复增删,插入耗时要在自己的数据分布上再压一轮。

哪些场景会用到有序映射

实际开发里,需要按键有序遍历的场景不算少。比如按编号区间整理的配置项,遍历出来希望编号从小到大;按时间戳或排序键归档的记录,输出时天然要有序;分组统计后要按键的大小顺序展示;去重集合之外还想附带一条值,又不想维护两个平行结构。这类场景如果用内置 dict,每次输出前都要 sorted(d.items()) 排一遍;如果底层结构本身有序,遍历一步到位,省去每次排序的步骤。

反过来,如果业务只按键查找、不关心遍历顺序,或者键类型五花八门不能在构造时固定,内置 dict 的哈希表写入更直接,也没必要引入有序结构。有序是有代价的:红黑树插入、删除要维护平衡,写入侧比哈希表多一层结构化开销,本轮千条插入 288.471 毫秒的读数就是这一侧成本的量级体现。选型时先判断“有序”是不是硬需求,再决定值不值得为它付写入侧的成本。

和内置 dict 的分工对照

把本轮实测到的特性并到一张表里:

维度 内置 dict BHA_Dict
顺序语义 保留插入顺序 按键升序遍历
类型声明 不声明,键值可混放 构造时固定 keytype/valuetype
底层结构 哈希表 StructRSBTSet 红黑树
重复键 覆盖值 覆盖值,不增节点
取值缺失 get 返回 None / 下标 KeyError 同左
拷贝 copy() 浅拷贝 copy() 独立副本
相等比较 与 dict 按内容比 与任意 MutableMapping 按内容比

什么时候用内置 dict 更合适:只是要一个键值查找表、不需要有序遍历、键值类型灵活、追求最快的哈希写入。什么时候再看 BHA_Dict:遍历结果必须按键大小有序、不想每次遍历前再 sorted、键类型可以在构造时固定、能接受红黑树写入的结构化开销。它不是用来替代 dict 的,而是在“需要有序映射”这个细分位置上提供一个底层有序的选项。

接入前建议先跑的边界用例

结合本轮实测,迁移到自己的业务前,建议先跑这几组用例:空字典上的 len、keys、values、items、布尔判断;重复键覆盖后长度是否保持;get、setdefault、update、pop 在命中和缺失两种情况下的返回;键类型自动转换在自己的真实键上是否成功;不存在键抛 KeyError 的捕获路径;copy 之后改副本是否影响原对象;浮点或其他包装类型读回后下游是否兼容;千条到万条规模下插入、遍历、取值的耗时是否在延迟预算内。另外建议在和生产同分布的键样本上跑一遍类型转换:本轮 keytype=str 时整数键会自动转字符串,如果业务键里同时存在数字与字符串两种写法,要先确认转换后的键是否符合预期,避免同义键被合并或拆分。

复核权威信息时我回 PyPI 查了实时版本和许可证:当前 9.13.12,Apache-2.0 OR MulanPSL-2.0,Python 要求 >=3.8,主依赖 numpy>=1.19.0;numba、cycy-runtime、cupy 是可选 extra。许可证分期上,9.12.6 及更早是 MIT,9.12.7 单一 Apache-2.0,9.12.8 起双许可,双 classifier 从 9.12.13 体现,合规要对着锁定版本核对。

和库里其他容器放一起看:主库的 BoolHybridArr 管的是布尔位的密集/稀疏混合存储,BHA_List 管的是嵌套列表结构,BHA_Queue 是队列,BHA_Dict 则是有序键值映射。它们解决的不是同一类问题:标记位选布尔数组,序列结构选 List,先进先出选 Queue,需要按键有序的键值对才落到 BHA_Dict。本轮实测只覆盖 BHA_Dict 的映射语义,序列化往返、跨结构嵌套等行为需要按对应接口另行实测,不在这篇结论范围内。

复盘记录

这轮实测下来,BHA_Dict 的定位比较清楚:一个类型固定、底层红黑树保序、对外贴合 Mapping 接口的有序映射。它的价值在于遍历天然有序,省掉每次 sorted 的步骤;代价是构造要声明类型、写入有红黑树维护护成本、包装类型在下游要确认兼容。选型时先想清楚自己要的是插入顺序还是按键有序,再决定用哪一类结构;本轮所有数字只对应本机 9.13.12、这批样本和这套测量口径,换到别的环境需要重新实测,不把局部结果当成全局定论。

posted @ 2026-11-21 21:42  贝壳bkshell  阅读(3)  评论(0)    收藏  举报