开发工具【免费下载链接】boltons Like builtins, but boltons. 250 constructs, recipes, and snippets which extend (and rely on nothing but) the Python standard library. Nothing like Michael Bolton.项目地址https://gitcode.com/gh_mirrors/bo/boltons点击查看免费下载导读boltons.dictutils是 boltons 项目中更有力量的映射类型模块其核心是OrderedMultiDict简称 OMD一个在保留插入顺序的同时、允许一个键对应多个值的 dict 子类被 docs/index.rst 定位为高度优化的 OrderedMultiDict并被 docs/architecture.rst 归入更强大的多用途数据结构类别。模块还提供一对一双向映射OneToOne、多对多映射ManyToMany、字典过滤工具subdict()以及可哈希的不可变字典FrozenDict。读完本文你将掌握 OMD 的完整 APIadd/getlist/todict/inverted/sorted/counts 等、其基于双向链表的底层实现原理以及其余四个工具的适用场景与用法并能在 URL 查询参数解析、反向索引、非破坏性数据叠加等真实场景中直接落地。本文主体内容来自 docs/dictutils.rstSphinx 自动文档入口所对应的模块文档字符串与各方法 docstring见 boltons/dictutils.py全部示例均可在 Python 交互环境中直接复现并有 tests/test_dictutils.py 中的测试用例佐证。为什么需要 OMD内置 dict 的取舍Python 核心自带强大的映射类型dict。它追求简单与性能一个快速的、无序的、1:1 的映射。在历史上它不保留插入顺序注2015 年起 PyPy 的基本 dict 已有序2017 年 12 月起 CPython 3 的基本 dict 也已有序见 boltons/dictutils.py也不允许一个键存多个值。OrderedMultiDict与内置dict形成鲜明对比它是一个相对极简主义的、有序的 1:n 的 dict 子类型。dict 的几乎每个特性都被重新打磨以在新增复杂度面前保持直观同时还新增了类似collections.Counter的功能方法。OMD 最大的优势是非破坏性non-destructive数据被加入 OMD 时不会被重排、也不会被覆盖。这一特性让开发者可以更自由地处理数据并能在不做任何额外工作的前提下对输入数据最终会落在输出的哪个位置做出更多假设。一个绝佳的例子是OMD.inverted()方法它返回一个新的 OMD把原键值互换值作键、键作值所有数据及其顺序在反转形式中依然完整保留。而同样的操作对内置dict或collections.OrderedDict而言是完全错误且鲁莽的。快速上手OMD 的基础用法OMD 的构造函数与内置 dict 完全一致整体 API 构成内置类型的一个直观超集 from boltons.dictutils import OrderedMultiDict # 或 OMD / MultiDict omd OrderedMultiDict() omd[a] 1 omd[b] 2 omd.add(a, 3) # add() 在键 a 下追加一个值 omd.get(a) 3 # get() 返回最近插入的值 omd.getlist(a) [1, 3] # getlist() 返回该键下全部值一些非 dict 风格的行为也值得一提比如支持reversed() list(reversed(omd)) [b, a]注意与其他一些 MultiDict 实现不同本 OMD优先返回最近插入的值——omd[a]指向3而不是1 omd OrderedMultiDict([(a, 1), (b, 2), (a, 3)]) omd.poplast(a) # 弹出最近插入的值 3 omd OrderedMultiDict([(a, 1), (b, 2)]) omd.pop(a) # pop 返回最近插入的值但删除该键全部值 1 omd OrderedMultiDict([(b, 2)])上面的poplast(a)弹出最近插入的3后键a仍保留值1而pop(a)返回最近值1后整个键及其全部值都被移除。若想得到一个安全可修改或扁平的字典请使用todict() from pprint import pprint as pp # 保持打印顺序 omd OrderedMultiDict([(a, 1), (b, 2), (a, 3)]) pp(omd.todict()) {a: 3, b: 2} pp(omd.todict(multiTrue)) {a: [1, 3], b: [2]}multiFalse默认时每个键以首次插入的顺序出现值为该键最近插入的值 OrderedMultiDict([(a, 1), (b, 2), (a, 3)]).items(multiFalse) [(a, 3), (b, 2)]关于dict(omd)的跨版本行为警告模块文档明确给出一个warningdict(omd)的行为在Python 3.7发生了改变因 CPython 从collections.OrderedDict过渡到内置字典有序。3.7 之前结果是新字典、值为列表类似于omd.todict(multiTrue)但只是浅拷贝列表直接引用 OMD 内部结构从 3.7 起值变成单值类似于omd.todict(multiFalse)。为了可靠的跨版本行为请直接使用omd.todict()。OMD 完整 API 与源码级原理解析底层实现双向链表 索引映射从源码结构看OMD 的插入顺序由一棵双向链表维护每条链上节点cell是一个四元素列表节点字段通过模块级常量定位PREV, NEXT, KEY, VALUE, SPREV, SNEXT range(6) # boltons/dictutils.py 第 80 行_insert()dictutils.py在链表尾部追加[last, root, k, v]节点_remove_all()dictutils.py则通过改写前后节点的指针完成摘除。正因底层是链表插入/删除只需 O(1) 指针操作__reversed__也能从root[PREV]起反向遍历dictutils.py。该模块还包含一个基于**跳表skip list**的变体FastIterOrderedMultiDictdictutils.py按键迭代更快且使用常量内存但插入重复键值对更慢。模块作者 Mark Williams 贡献了该实现misc/bench_omd.py 中保留了针对 OMD、FastIterOrderedMultiDict、collections.OrderedDict、内置 dict以及可选的 werkzeug MultiDict的基准对比脚本该脚本依赖外部项目路径与 lithoxyl 库仅供本地基准参考。增删改add / addlist / setdefault / update / update_extend / pop 家族方法语义源码位置add(k, v)在键k下追加单个值保留已有值dictutils.pyaddlist(k, v)在键k下追加一个可迭代对象的全部值保留已有值空迭代直接返回dictutils.pyget(k, defaultNone)返回最近插入的值不抛 KeyErrordictutils.pygetlist(k, default)返回该键全部值的副本可安全修改无 default 时返回空列表dictutils.pysetdefault(k, defaultNone)键不存在则写入默认值并返回它存在则返回当前值dictutils.pyupdate(E, **F)合并数据并覆盖已有键的值dictutils.pyupdate_extend(E, **F)合并数据但不覆盖追加到已有键下dictutils.pypop(k, default)移除键下全部值返回最近插入的值dictutils.pypopall(k, default)移除键下全部值以列表形式返回dictutils.pypoplast(k, default)弹出最近插入的值不传k时弹出最近插入的键dictutils.pyclear()清空dictutils.pycopy()/fromkeys(keys, default)浅拷贝 / 从键列表构造dictutils.pyaddlist的 docstring 示例 omd OrderedMultiDict([(a, -1)]) omd.addlist(a, range(3)) omd OrderedMultiDict([(a, -1), (a, 0), (a, 1), (a, 2)])注意update()与update_extend()的关键区别前者覆盖omd.update(omd2)后getlist(a) [10]见 tests/test_dictutils.py 的test_update_basic后者则在已有键下追加测试 test_update_extend 断言len(omd1.getlist(k)) len(omd2.getlist(k))。另外 OMD 支持|就地合并运算符__ior__dictutils.py测试见 test_ior。遍历与视图multi 标志的妙用iteritems/iterkeys/itervalues以及返回列表的items/keys/values都接受multi布尔参数dictutils.py默认multiFalse每个键只出现一次值取最近插入的那个multiTrue按插入顺序产出全部条目含重复键。 omd OrderedMultiDict([(a, 1), (b, 2), (a, 3)]) omd.items() [(a, 3), (b, 2)] omd.items(multiTrue) [(a, 1), (b, 2), (a, 3)] omd.keys(multiTrue) [a, b, a]test_kv_consistencytests/test_dictutils.py验证了两种模式下keys/values与items的顺序严格一致。iterkeys(multiTrue)的实现是直接沿链表推进而iterkeys()非 multi用yielded集合去重后按首次出现顺序产出唯一键。模块还提供viewkeys()/viewvalues()/viewitems()三套视图dictutils.py基于collections.abc的 KeysView/ValuesView/ItemsView。排序sorted 与 sortedvaluessorted(keyNone, reverseFalse)dictutils.py返回一个按 key 函数排序的新 OMD其 key 函数接收的是条目key-value 二元组 omd OrderedMultiDict(zip(range(3), range(3))) omd.sorted(reverseTrue) OrderedMultiDict([(2, 2), (1, 1), (0, 0)]) omd OrderedMultiDict(zip(hello, world)) omd.sorted(keylambda i: i[1]) # i[0] 是键i[1] 是值 OrderedMultiDict([(o, d), (l, l), (e, o), (l, r), (h, w)])sortedvalues(keyNone, reverseFalse)dictutils.py则保持键及键的顺序不变只对每个键空间内的值排序 omd OrderedMultiDict() omd.addlist(even, [6, 2]) omd.addlist(odd, [1, 5]) omd.add(even, 4) omd.add(odd, 3) somd omd.sortedvalues() somd.getlist(even) [2, 4, 6] somd.keys(multiTrue) omd.keys(multiTrue) True omd somd False somd OrderedMultiDict([(even, 2), (even, 4), (odd, 1), (odd, 3), (even, 6), (odd, 5)])如上所示内容与键顺序被完整保留只有值的顺序发生变化。注意sortedvalues的实现在重插时按逆序弹出处理源码注释# (not reverse)因此反向排序时传reverseTrue的语义与直觉略有不同使用时建议以 doctest 行为为准。反转与计数inverted 与 countsinverted()dictutils.py返回一个新的 OMD值变键、键变值插入顺序保留、所有数据完整呈现——这正是非破坏性哲学的集中体现可用来构建反向索引 omd OMD([(0, 2), (1, 2)]) omd.inverted().getlist(2) [0, 1]反转两次得到原对象的副本 omd.inverted().inverted() OrderedMultiDict([(0, 2), (1, 2)])counts()dictutils.py返回键 → 该键下插入值数量的映射类似collections.Counter但返回的是新的 OrderedMultiDict源码注释解释了原因Counter/OrderedDict 可能不可用且 Counter 与 dict 都不保证顺序 omd OMD([(a, 1), (b, 2), (a, 3)]) omd.counts() OrderedMultiDict([(a, 2), (b, 1)])相等性、序列化与视图相等性__eq__dictutils.py与另一个 OMD 比较时逐条含 multi 全部条目比较与普通 dict 比较时按每键最近值比较。测试 test_eq 验证了omd d以及dict(itemset)构造的 OMD 与原始 OMD 相等。pickle 支持__getstate__/__setstate__dictutils.py以 multi 条目列表作为序列化状态test_omd_pickletests/test_dictutils.py验证了空与非空 OMD 的 roundtripgetlist(b) [2, 3]说明多值被完整保留。构造约束__init__限制最多 1 个位置参数超出抛TypeError位置参数走update_extend不覆盖关键字参数走update覆盖——这一细节来自 dictutils.py。别名模块末尾提供了便捷别名dictutils.pyOMD OrderedMultiDict、MultiDict OrderedMultiDict三者可互换使用。项目内的真实应用URL 查询参数dictutils并非孤立模块。在 boltons 自己的 urlutils 中URL.query_params是QueryParamDict的实例而QueryParamDict正是OrderedMultiDict 的子类型用于承载问号之后的文本键值对还提供别名qp url URL(http://boltons.readthedocs.io/en/latest/?utm_sourcedocssphinxok) url.qp.keys() [utm_source, sphinx]这也解释了为什么 OMD 需要一个键多个值URL 查询参数天然允许?a1a2这样的重复键且顺序有语义。相关实现可见 boltons/urlutils.py其中保留了 OMD 的嵌入式副本用于 QueryParamDict。在URL.__init__中query_params参数接受 OMD、dict 或 (key, value) 列表boltons/urlutils.py。OneToOne自动维护反向映射的一对一字典OneToOnedictutils.py实现一对一映射除继承并完全像内置 dict 一样工作外所有值会被自动加入反向映射以inv属性暴露键与值的命名空间相互独立。 from boltons.dictutils import OneToOne oto OneToOne({a: 1, b: 2}) print(oto[a]) 1 print(oto.inv[1]) a len(oto) 2双向覆盖同样生效 oto.inv[1] c # 反向覆盖 print(oto.get(a)) None # 原键 a 被移除 len(oto) 2源码要点通过_OTO_INV_MARKER哨兵实现正向/反向字典的内部互建避免递归构造dictutils.py__setitem__先hash(val)保证值可作为键再同步维护两个方向dictutils.py值不唯一时默认以后写覆盖收敛为合法的一对一映射测试 test_one_to_one 验证了OneToOne({a: 0, b: 0})收敛为len(oto) len(oto.inv) 1OneToOne.unique(*a, **kw)dictutils.py是严格构造器输入值一旦重叠立即抛ValueErrorexpected unique values, got multiple keys for the following values: ...对 dict 与关键字参数混合输入同样生效 OneToOne.unique({a: 1, b: 1}) Traceback (most recent call last): ... ValueError: expected unique values, got multiple keys for the following values: ... a_dict {a: 2} OneToOne.unique(a_dict, b2) Traceback (most recent call last): ... ValueError: ...pop/popitem/setdefault/clear/update均被重写以保持双向一致update会先hash所有输入值再逐项写入dictutils.py。ManyToMany多对多关系与有向图ManyToManydictutils.py是类字典实体表示两组对象之间的多对多关系行为类似dict-of-tuples并带有始终保持同步的.inv反方向同样是 dict-of-tuples。它还可以当作由可哈希 Python 对象构成的有向图使用。 from boltons.dictutils import ManyToMany m2m ManyToMany() m2m.add(1, a) m2m.add(1, b) m2m[1] # __getitem__ 返回 frozenset 视图 frozenset({a, b}) m2m.inv[a] frozenset({1}) m2m.get(3) # 缺省键返回空 frozenset不抛异常 frozenset()常用操作add(key, val)/remove(key, val)双向同步增删dictutils.py__setitem__(key, vals)整组替换关联集合内部计算差集增量增删dictutils.pyreplace(key, newkey)把 key 的所有关联整体迁移到 newkey 下dictutils.pyupdate(iterable)接受本类型实例、有keys的对象或(key, val)可迭代dictutils.py支持len、in、迭代、与repr。测试 test_many_to_many 验证了双向删除的级联效果del m2m.inv[a]后m2m[1]只剩b、ManyToMany([ab, cd]) ManyToMany([ba, dc]).inv的反向对称性以及replace行为。subdict按 keep/drop 过滤字典subdict(d, keepNone, dropNone)dictutils.py计算字典的子字典——subdict 之于 dict正如 subset 之于 set若 A 是 B 的 subdict则 A 的所有键都在 B 中出现。它返回一个新字典移除drop中的键、保留keep中的键仅当原字典中存在。keep默认全部键drop默认空因此两个参数都不传时等价于dict() from boltons.dictutils import subdict from pprint import pprint as pp pp(subdict({a: 1, b: 2})) {a: 1, b: 2} subdict({a: 1, b: 2, c: 3}, drop[b, c]) {a: 1} pp(subdict({a: 1, b: 2, c: 3}, keep[a, c])) {a: 1, c: 3}实现用set(keep) - set(drop)求保留键集合并以type(d)构造返回值dictutils.py因此尽量保持传入字典的类型——测试 test_subdict_keep_type 断言subdict(omd)的类型仍是 OMD。drop与keep也可同时使用如test_subdict中的subdict(cap_map, drop[a])tests/test_dictutils.py。FrozenDict可哈希的不可变字典FrozenDictdictutils.py是不可变的 dict 子类型可哈希能直接作为 dict 的键或 set 的元素——正如frozenset之于setFrozenDict 之于dict。曾有提议将其引入标准库但被拒绝PEP 416详见模块 docstring dictutils.py。由于 FrozenDict 是 dict 子类型它自动适用于任何 dict 可用的场合包括 JSON 序列化 from boltons.dictutils import FrozenDict fd FrozenDict({a: A, b: B}) fd[a] A hash(fd) # 可哈希 {fd: fd}[fd] is fd # 可作为 dict 键 True不可变性所有修改型方法__setitem__、__delitem__、update、setdefault、pop、popitem、clear、|统一抛TypeError: FrozenDict object is immutabledictutils.py。测试 test_frozendict 逐项验证了这些异常。实用特性updated(*a, **kw)dictutils.py复制并追加条目覆盖已有键返回新FrozenDict——这是不可变映射的标准修改方式 fkfd FrozenDict.fromkeys([2, 4, 6], value0) sorted(fkfd.updated({8: 0}).keys()) [2, 4, 6, 8]FrozenDict.fromkeys(keys, valueNone)dictutils.py__hash__基于hash(frozenset(self.items()))并缓存在_hash槽位若值不可哈希缓存的FrozenHashErrorTypeError子类dictutils.py会被原样重抛且同一异常对象被缓存复用——测试断言两次{unfd: val}抛出的是同一异常实例tests/test_dictutils.py__copy__返回自身不可变类型无需复制与 tuple 行为一致且实现了 pickle 支持__reduce_ex__。测试与可靠性保障dictutils的每个核心行为都有对应测试集中在 tests/test_dictutils.py正确性test_multi_correctness第 113 行用 100 个键、5 倍冗余的构造数据验证两种multi模式下迭代值严格升序即插入顺序完整保留一致性test_kv_consistency第 129 行验证 keys/values/items 顺序互洽兼容性test_types第 105 行断言 OMD 既是dict又是collections.abc.MutableMapping的实例边界test_addlist第 222 行验证addlist(a, [])不产生任何条目test_setdefault第 282 行验证返回对象身份x is empty_listPython 3.9 特性test_frozendict_ior第 479 行验证 PEP 584 的|对 FrozenDict 抛TypeError。运行方式pytest tests/test_dictutils.py依赖见 requirements-test.txt。小结如何选择 dictutils 中的类型类型/函数核心特性典型场景OrderedMultiDict/OMD/MultiDict有序 一键多值 非破坏性URL 查询参数、反向索引、多源数据非破坏性叠加见 docs/index.rst 的项目定位FastIterOrderedMultiDict跳表实现按键迭代更快、常量内存读多写少、需要频繁全量遍历的场景OneToOne双向映射自动同步inv属性用户↔ID、缩写↔全称等唯一映射正反查询ManyToMany多对多关系双向inv同步标签↔文章、权限↔角色、有向图建模subdict(d, keep, drop)按 keep/drop 过滤尽量保持原类型请求参数白名单、字段裁剪FrozenDict不可变、可哈希、dict 子类型配置常量、可哈希缓存键、安全共享只读映射# 一行导入全部所需工具 from boltons.dictutils import (OrderedMultiDict, OMD, MultiDict, OneToOne, ManyToMany, subdict, FrozenDict)完整 API 文档入口位于 docs/dictutils.rst模块变更历史可查阅 CHANGELOG.md 中dictutils相关条目如 OMD pickle 修复、ior支持、sorted()保留全部条目、OneToOne 空可迭代 update 修复等。赞分享开发工具【免费下载链接】boltons Like builtins, but boltons. 250 constructs, recipes, and snippets which extend (and rely on nothing but) the Python standard library. Nothing like Michael Bolton.项目地址https://gitcode.com/gh_mirrors/bo/boltons点击查看免费下载相关推荐MikroORM 实体关系建模全指南ManyToOne / OneToMany / OneToOne / ManyToMany 的声明与双向关联详解MikroORM 实体关系建模全指南ManyToOne / OneToMany / OneToOne / ManyToMany 的声明与双向关联详解 Mikr后端PyO3 类型转换完全指南Python 与 Rust 类型映射、FromPyObject 与 IntoPyObject 实战PyO3 类型转换完全指南Python 与 Rust 类型映射、FromPyObject 与 IntoPyObject 实战 PyO3 的核心价值在于让 Ru开发工具GraalWasm 实战指南在 Java 中嵌入 WebAssembly 模块的模块系统、类型映射与选项配置GraalWasm 实战指南在 Java 中嵌入 WebAssembly 模块的模块系统、类型映射与选项配置 GraalWasm 是 GraalVM 项目本编译器JIT编译语言运行时高性能计算内存管理上一篇Moya 单元测试与接口 Mock 实战深入 sampleData、stubClosure 与 EndpointSampleResponse下一篇Pandoc 嵌套列表转换深度解析HTML 到 Markdown 的实现与命令行测试test/command/8150.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考