在 Python 编程中，字典（dict）是用于存储键值对的强大数据结构，能够快速地根据键查找值。然而，有时我们不仅需要从键查找值，还需要根据值查找键。这种双向查询需求在很多场景中很常见，如映射表、缓存系统、反向索引等。如果我们依赖原生字典实现双向映射，可能需要维护两个字典，代码复杂度也随之增加。

bidict 库正是为了解决这一问题而设计的，它是一个高效且安全的双向字典实现，能够同时支持键到值以及值到键的双向映射。在不损失性能的前提下，bidict 提供了简洁的 API，使得开发者可以方便地在各种应用场景中使用双向字典。

本文将介绍 bidict 的主要功能、应用场景，并通过代码示例演示如何在 Python 项目中使用 bidict 实现高效的双向映射。

💯 bidict 的特点

bidict 库相比 Python 的原生字典有如下几个显著特点：

1. 双向映射：bidict 支持同时根据键查值和根据值查键，简化了双向映射场景下的代码编写。
2. 自动去重：bidict 确保字典中的键和值都是唯一的，防止重复的键或值导致数据混乱。
3. 高效性：与维护两个原生字典相比，bidict 在内存和性能上都更加高效。
4. 错误处理：bidict 提供了丰富的错误处理机制，确保在插入冲突时抛出合理的异常。

💯 安装 bidict

要使用 bidict，首先需要通过 pip 安装：

pip install bidict

安装完成后，就可以在 Python 项目中使用 bidict 来实现双向字典功能。

💯 bidict 的基本用法

bidict 的 API 非常类似于 Python 的原生字典，因此对于熟悉 Python 字典的开发者来说，上手 bidict 非常简单。下面是一些基本的用法示例。

1. 创建双向字典

创建一个双向字典与创建普通字典的方式类似。你可以传入键值对来初始化 bidict。

from bidict import bidict

# 创建一个双向字典
b = bidict({'a': 1, 'b': 2, 'c': 3})

print(b['a'])  # 输出: 1
print(b.inv[1])  # 通过值查找键，输出: 'a'

在这个示例中，我们创建了一个字典 b，可以通过 b['a'] 查找键对应的值，也可以通过 b.inv[1] 反向查找值对应的键。inv 属性是 bidict 提供的用于反向查找的接口。

2. 插入和更新键值对

像普通字典一样，bidict 允许你添加或更新键值对。

b = bidict()

# 插入键值对
b['x'] = 10
b['y'] = 20

# 更新键值对
b['x'] = 30

# 反向查询
print(b.inv[30])  # 输出: 'x'

在这个示例中，我们首先插入了一对键值 x: 10，然后更新了键 x 对应的值为 30，并通过反向查询得到了 x。

3. 自动去重与冲突检测

bidict 确保了字典中的键和值都是唯一的。如果你尝试插入一个重复的键或值，bidict 会抛出 ValueError 异常。

from bidict import bidict, ValueDuplicationError

b = bidict({'a': 1, 'b': 2})

# 尝试插入重复的值
try:
    b['c'] = 1  # 1 已经作为 'a' 的值存在
except ValueDuplicationError as e:
    print(f"错误: {e}")

在这个示例中，尝试插入重复的值 1 会抛出 ValueDuplicationError，因为 1 已经作为 a 的值存在。

4. 反向字典（.inv 属性）

bidict 的 inv 属性用于创建一个反向字典，允许根据值查找键。这种反向映射的功能在数据结构、索引系统等场景中非常有用。

b = bidict({'apple': 'red', 'banana': 'yellow'})

# 通过键查找值
print(b['apple'])  # 输出: red

# 通过值查找键
print(b.inv['red'])  # 输出: apple

b.inv 提供了一个反向映射视图，使得你可以轻松进行双向查找。

💯 高级功能

1. 强制更新模式

在某些情况下，你可能希望允许键值对的冲突，并且强制更新字典中的值。bidict 支持通过 on_dup 参数来控制冲突处理行为。你可以使用 on_dup='overwrite' 强制覆盖冲突的键或值。

from bidict import bidict

# 使用强制覆盖模式
b = bidict({'a': 1, 'b': 2})

# 强制覆盖值
b.put('c', 1, on_dup='overwrite')

print(b)  # 输出: bidict({'b': 2, 'c': 1})

在这个示例中，put 方法强制覆盖了键 c，并且值 1 也被覆盖到新的键 c。

2. 冻结字典：不可变的双向字典

bidict 提供了 FrozenBidict 类型，这是一种不可变的双向字典，类似于 Python 中的 frozenset，适用于需要只读访问的数据场景。

from bidict import FrozenBidict

frozen_b = FrozenBidict({'a': 1, 'b': 2})

# 尝试修改会抛出异常
try:
    frozen_b['c'] = 3
except TypeError as e:
    print(f"错误: {e}")

FrozenBidict 可以确保字典中的数据不会被修改，适用于那些需要数据完整性保障的场景。

3. 扩展 bidict：Bidirectional Mapping

bidict 也可以作为其他高级数据结构的基础，比如用于构建双向缓存、双向映射关系等。通过结合 LRU Cache 或其他数据结构，bidict 可以应用于更多复杂的场景。

💯 bidict 的应用场景

bidict 提供的双向映射特性在许多场景中非常有用，以下是一些典型的应用场景：

1. 缓存系统

在缓存系统中，我们常常需要根据键查找缓存的值，也需要反向根据缓存的值查找到对应的键。使用 bidict，可以高效地实现这样的双向映射。

2. 编码与解码

在编码与解码过程中，开发者通常需要维护一对一的映射关系，例如字符编码表、哈希函数映射等。bidict 能够轻松实现编码和解码的双向查询，简化代码逻辑。

3. 数据索引与查找

在某些数据库或搜索引擎中，我们需要快速从键查找值（正向索引）或从值查找键（反向索引）。bidict 作为一种轻量级的数据结构，适合构建内存中的索引系统。

4. 构建反向映射关系

在图论或网络模型中，节点之间的双向映射关系非常常见。使用 bidict 可以方便地构建这些双向的节点关系，并且在复杂的图结构中高效处理数据。

📥 下载地址

bidict 最新版 下载地址

💬 结语

bidict 是一个专门为双向映射设计的高效 Python 库，它简化了在开发中需要同时维护键值对正反查找的场景。通过类似原生字典的 API 和反向字典支持，bidict 提供了简洁、强大的双向映射解决方案。无论是在缓存、编码、索引等复杂数据结构中，还是在处理普通的键值映射中，bidict 都是一个值得推荐的工具。

📒 参考文献

• bidict 官方文档
• bidict GitHub仓库