intro.rst

Introduction

The bidict library provides several friendly, efficient data structures for working with bidirectional mappings in Python.

bidict.bidict

bidict.bidict is the main bidirectional mapping data structure provided. It allows looking up the value associated with a key, just like a dict:

>>> element_by_symbol = bidict({'H': 'hydrogen'}) >>> element_by_symbol['H'] 'hydrogen'

But it also allows looking up the key associated with a value, via the special ~bidict.BidictBase.inverse attribute:

>>> element_by_symbol.inverse['hydrogen'] 'H'

The ~bidict.BidictBase.inverse attribute actually references the entire inverse bidirectional mapping:

>>> element_by_symbol bidict({'H': 'hydrogen'}) >>> element_by_symbol.inverse bidict({'hydrogen': 'H'})

...which is automatically kept in sync as the original mapping is updated:

>>> element_by_symbol['H'] = 'hydrogène' >>> element_by_symbol.inverse bidict({'hydrogène': 'H'})

If you're used to working with dicts, you'll feel right at home using bidict:

>>> dir(element_by_symbol) [..., '__getitem__', ..., '__setitem__', ..., 'items', 'keys', ...]

Familiar, concise, Pythonic.

Why can't I just use a dict?

A skeptic writes:

If I want a mapping associating a → *b* and b → *a*, I can just create the dict {a: b, b: a}. Why bother using bidict?

One answer is better ergonomics for maintaining a correct representation. For example, to get the correct length, you'd have to take the number reported by len and cut it in half.

But now consider what happens when we need to store a new association, and we try to do so naively:

el_by_sym = {'H': 'hydrogen', 'hydrogen': 'H'}
# Later we need to associate 'H' with a different value
el_by_sym.update({'H': 'hydrogène', 'hydrogène': 'H'}  # Too naive

Here is what we're left with:

# el_by_sym:
{'H': 'hydrogène', 'hydrogène': 'H', 'hydrogen': 'H'}

Oops.

We forgot to look up whether the key and value we wanted to set already had any previous associations and remove them as necessary.

In general, if we want to store the association k ⟷ *v*, but we may have already stored the associations k ⟷ *v′* or k′ ⟷ *v*, a correct implementation using the single-dict approach would require code like this:

>>> d = {'H': 'hydrogen', 'hydrogen': 'H'}

>>> def update(d, key, val): ... oldval = d.pop(key, object()) ... d.pop(oldval, None) ... oldkey = d.pop(val, object()) ... d.pop(oldkey, None) ... d.update({key: val, val: key})

>>> update(d, 'H', 'hydrogène') >>> d == {'H': 'hydrogène', 'hydrogène': 'H'} True

With bidict, we can instead just write:

>>> b = bidict({'H': 'hydrogen'}) >>> b['H'] = 'hydrogène'

And bidict takes care of all the fussy details, leaving us with just what we wanted:

>>> b bidict({'H': 'hydrogène'})

>>> b.inverse bidict({'hydrogène': 'H'})

Even more important...

Beyond this, consider what would happen if we needed to work with just the keys, values, or items that we have associated.

Since the single-dict approach inserts values as keys into the same dict that it inserts keys into, we'd never be able to tell our keys and values apart.

So iterating over the keys would also yield the values (and vice versa), with no way to tell which was which.

Iterating over the items would yield twice as many as we wanted, with a (v, k) item that we'd have to ignore for each (k, v) item that we expect, and no way to tell which was which.

>>> # Compare the single-dict approach: >>> set(d.keys()) == {'H', 'hydrogène'} # .keys() also gives values True >>> set(d.values()) == {'H', 'hydrogène'} # .values() also gives keys True

>>> # ...to using a bidict: >>> b.keys() == {'H'} # just the keys True >>> b.values() == {'hydrogène'} # just the values True

In short, to model a bidirectional mapping correctly and unambiguously, we need two separate one-directional mappings, one for the forward associations and one for the inverse, that are kept in sync as the associations change.

This is exactly what bidict does under the hood, abstracting it into a clean and ergonomic interface.

bidict's APIs also provide power, flexibility, and safety, making sure the one-to-one invariant is maintained and inverse mappings are kept consistent, while also helping make sure you don't accidentally shoot yourself in the foot <basic-usage:Values Must Be Unique>.

Additional Functionality

Besides the standard bidict.bidict type, the bidict module provides other bidirectional mapping variants: ~bidict.frozenbidict and ~bidict.OrderedBidict.

These and bidict's other functionality will be covered in later sections.

But first, let's look at a few more details of basic-usage.