Bidirectional Mapping Library

0.23.1 · active · verified Sun Mar 29

The bidict library for Python provides efficient and Pythonic data structures for working with bidirectional (one-to-one) mappings. It offers familiar dictionary-like APIs, automatically keeping forward and inverse mappings in sync. The library is mature, actively maintained, and currently at version 0.23.1, with a regular release cadence. [1, 3, 10]

Warnings

breaking The `.inv` attribute for accessing the inverse mapping was renamed to `.inverse`. While `.inv` was an alias for a period, it's recommended to use `.inverse` for clarity and future compatibility.
Fix: Replace `.inv` with `.inverse`.
breaking Support for Python 3.6 was dropped. If you are using bidict with Python 3.6, you must remain on an older version of the library or upgrade your Python interpreter.
Fix: Upgrade to Python 3.8+ (recommended `bidict` requirement) or ensure your `bidict` version is pinned to <0.22.0.
breaking Several old APIs, including the `on_dup_key`, `on_dup_val`, and `on_dup_kv` arguments to `put()` and `putall()`, as well as the constants `bidict.OVERWRITE` and `bidict.IGNORE`, were removed.
Fix: Consult the changelog for `bidict` 0.20.0 for alternative approaches to handling duplicate key/value scenarios. [2]
gotcha Unlike standard `dict` values, values stored in a `bidict` must be hashable. This is because values serve as keys in the inverse mapping, and keys must always be hashable in Python dictionaries.
Fix: Ensure that any values you intend to store in a `bidict` are immutable and hashable (e.g., strings, numbers, tuples). [6]
gotcha For `OrderedBidict`, the `==` operator (`__eq__`) performs an order-insensitive comparison, similar to regular `dict`s. If you require order-sensitive equality checking, use the `equals_order_sensitive()` method.
Fix: Use `my_ordered_bidict.equals_order_sensitive(other_bidict)` for order-aware comparisons. [9, 14]
gotcha Attempting to create a bidirectional mapping using two separate `dict`s or a single `dict` with duplicated key/value entries is error-prone and leads to manual synchronization issues and potential data inconsistency. `bidict` handles these invariants automatically.
Fix: Always use `bidict` for one-to-one bidirectional mappings to ensure consistency and correctness. [1, 4, 6]
deprecated The `bidict.__version_info__` attribute was removed.
Fix: Use `import importlib.metadata; importlib.metadata.version('bidict')` or `bidict.__version__` to get the version string. [2]

Install

pip install bidict Install bidict

Imports

bidict
```
from bidict import bidict
```
bidict.inv
```
my_bidict.inverse
```
The `.inv` attribute was renamed to `.inverse` in v0.18.0. `inv` became an alias but `inverse` is the canonical and recommended name. [2, 5]

Quickstart

This example demonstrates creating a basic bidirectional mapping, accessing forward and inverse entries, and observing how updates are automatically synchronized. [3, 10]

from bidict import bidict

element_by_symbol = bidict({'H': 'hydrogen'})
print(f"Forward mapping: {element_by_symbol['H']}")
print(f"Inverse mapping: {element_by_symbol.inverse['hydrogen']}")

# Updates are automatically synchronized in both directions
element_by_symbol['H'] = 'hydrogène'
print(f"Updated forward mapping: {element_by_symbol['H']}")
print(f"Updated inverse mapping: {element_by_symbol.inverse['hydrogène']}")

view raw JSON →