Basic Usage

Let’s return to the example from the Introduction:

>>> from bidict import bidict
>>> element_by_symbol = bidict(H='hydrogen')

As we saw, this behaves just like a dict, but maintains a special inv attribute giving access to inverse mappings:

>>> element_by_symbol.inv['helium'] = 'He'
>>> del element_by_symbol.inv['hydrogen']
>>> element_by_symbol
bidict({'He': 'helium'})

The rest of the collections.abc.MutableMapping ABC is also supported:

>>> 'C' in element_by_symbol
False
>>> element_by_symbol.get('C', 'carbon')
'carbon'
>>> element_by_symbol.pop('He')
'helium'
>>> element_by_symbol
bidict()
>>> element_by_symbol.update(Hg='mercury')
>>> element_by_symbol
bidict({'Hg': 'mercury'})
>>> 'mercury' in element_by_symbol.inv
True
>>> element_by_symbol.inv.pop('mercury')
'Hg'

Because inverse mappings are maintained alongside forward mappings, referencing a bidict’s inverse is always a constant-time operation.

Values Must Be Hashable

Because you must be able to look up keys by value as well as values by key, values must also be hashable.

Attempting to insert an unhashable value will result in an error:

>>> from bidict import bidict
>>> anagrams_by_alphagram = bidict(opt=['opt', 'pot', 'top'])
Traceback (most recent call last):
    ...
TypeError...

In this example, using a tuple instead of a list does the trick:

>>> bidict(opt=('opt', 'pot', 'top'))
bidict({'opt': ('opt', 'pot', 'top')})

Uniqueness of Values

As we know, in a bidirectional map, not only must keys be unique, but values must be unique as well. This has immediate implications for bidict’s API.

Consider the following:

>>> from bidict import bidict
>>> b = bidict({'one': 1})
>>> b['two'] = 1  

What should happen next?

If the bidict allowed this to succeed, because of the uniqueness-of-values constraint, it would silently clobber the existing item, resulting in:

>>> b  
bidict({'two': 1})

This could result in surprises or problems down the line.

Instead, bidict raises a ValueDuplicationError so you have an opportunity to catch this early and resolve the conflict before it causes problems later on:

>>> b['two'] = 1
Traceback (most recent call last):
    ...
ValueDuplicationError: 1

The purpose of this is to be more in line with the Zen of Python, which advises,

Errors should never pass silently.
Unless explicitly silenced.

Similarly, initializations and update() calls that would overwrite the key of an existing value raise an exception too:

>>> bidict({'one': 1, 'uno': 1})
Traceback (most recent call last):
    ...
ValueDuplicationError: 1
>>> b = bidict({'one': 1})
>>> b.update([('two', 2), ('uno', 1)])
Traceback (most recent call last):
    ...
ValueDuplicationError: 1

If an update() call raises, you can be sure that none of the supplied items were inserted:

>>> b
bidict({'one': 1})

Setting an existing key to a new value does not cause an error, and is considered an intentional overwrite of the value associated with the existing key, in keeping with dict’s behavior:

>>> b = bidict({'one': 1})
>>> b['one'] = 2  # succeeds
>>> b
bidict({'one': 2})
>>> b.update([('one', 3), ('one', 4), ('one', 5)])
>>> b
bidict({'one': 5})
>>> bidict([('one', 1), ('one', 2)])
bidict({'one': 2})

In summary, when attempting to insert an item whose key duplicates an existing item’s, bidict’s default behavior is to allow the insertion, overwriting the existing item with the new one. When attempting to insert an item whose value duplicates an existing item’s, bidict’s default behavior is to raise. This design naturally falls out of the behavior of Python’s built-in dict, and protects against unexpected data loss.

One set of alternatives to this behavior is provided by forceput() and forceupdate(), which allow you to explicitly overwrite existing keys and values:

>>> b = bidict({'one': 1})
>>> b.forceput('two', 1)
>>> b
bidict({'two': 1})
>>> b.forceupdate({'three': 1})
>>> b
bidict({'three': 1})

For even more control, you can use put() instead of forceput() or __setitem__(), and putall() instead of update() or forceupdate(). These methods allow you to specify different strategies for handling key and value duplication via the on_dup_key, on_dup_val, and on_dup_kv arguments. Three possible options are RAISE, OVERWRITE, and IGNORE:

>>> from bidict import RAISE, OVERWRITE, IGNORE
>>> b = bidict({2: 4})
>>> b.put(2, 8, on_dup_key=RAISE)
Traceback (most recent call last):
    ...
KeyDuplicationError: 2
>>> b.putall([(3, 9), (2, 8)], on_dup_key=RAISE)
Traceback (most recent call last):
    ...
KeyDuplicationError: 2
>>> b  # Note that (3, 9) was not added because the call failed:
bidict({2: 4})
>>> b.putall([(3, 9), (1, 4)], on_dup_val=IGNORE)
>>> sorted(b.items())  # Note (1, 4) was ignored as requested:
[(2, 4), (3, 9)]

If not specified, the on_dup_key and on_dup_val keyword arguments of put() and putall() default to RAISE, providing stricter-by-default alternatives to __setitem__() and update(). (These defaults complement the looser alternatives provided by forceput() and forceupdate().)

on_dup_kv

Note that it’s possible for a given item to duplicate the key of one existing item, and the value of another existing item. This is where on_dup_kv comes in:

>>> b.putall([(4, 16), (5, 25), (4, 25)],
...          on_dup_key=IGNORE, on_dup_val=IGNORE, on_dup_kv=RAISE)
Traceback (most recent call last):
    ...
KeyAndValueDuplicationError: (4, 25)

Because the given on_dup_key and on_dup_val behaviors may differ, on_dup_kv allows you to indicate how you want to handle this case without ambiguity. If not specified, on_dup_kv defaults to ON_DUP_VAL, meaning on_dup_kv will match whatever on_dup_val behavior is in effect.

Note that if an entire (k, v) item is duplicated exactly, the duplicate item will just be ignored, no matter what the duplication behaviors are set to. The insertion of an entire duplicate item is construed as a no-op:

>>> b.put(2, 4)
>>> sorted(b.items())
[(2, 4), (3, 9)]
>>> b.putall([(4, 16), (4, 16)])
>>> sorted(b.items())
[(2, 4), (3, 9), (4, 16)]

loosebidict

If you know you’re going to want all- OVERWRITE behaviors more often than not, an alternative to using forceput() and forceupdate() is to use a loosebidict instead. loosebidict ’s __setitem__() and update() methods use OVERWRITE behaviors by default:

>>> from bidict import loosebidict
>>> b = loosebidict({'one': 1})
>>> b['two'] = 1  # succeeds, no ValueDuplicationError
>>> b
loosebidict({'two': 1})
>>> b.update({'three': 1})  # ditto
>>> b
loosebidict({'three': 1})

As with bidict.bidict, loosebidict.put() and loosebidict.putall() still provide per-call overrides for duplication behaviors, and they all still default to RAISE.

Beware on_dup_kv=OVERWRITE

Beware that on_dup_kv=OVERWRITE semantics (which loosebidict uses by default) cause the following potentially surprising behavior:

>>> from bidict import loosebidict
>>> b = loosebidict({'one': 1, 'two': 2})
>>> b['one'] = 2
>>> b
loosebidict({'one': 2})

That is, setting an existing key to the value of a different existing item causes both existing items to be collapsed into a single item.

Order Matters

Performing a bulk insert operation (e.g. on initialization or via update(), forceupdate(), or putall()), is like performing a sequence of single insert operations for each of the provided items (with the advantage that the bulk insert fails clean, i.e. if it fails, it will be as if none of the single insert operations were ever called). Therefore, the order of the items provided to the bulk insert operation may affect the result:

>>> from bidict import bidict
>>> b = bidict({0: 0, 1: 2})
>>> b.forceupdate([(2, 0), (0, 1), (0, 0)])
>>> # 1. (2, 0) overwrites (0, 0)             -> bidict({2: 0, 1: 2})
>>> # 2. (0, 1) is added                      -> bidict({2: 0, 1: 2, 0: 1})
>>> # 3. (0, 0) overwrites (0, 1) and (2, 0)  -> bidict({0: 0, 1: 2})
>>> sorted(b.items())
[(0, 0), (1, 2)]
>>> b = bidict({0: 0, 1: 2})  # as before
>>> # Give same items to forceupdate() but in a different order:
>>> b.forceupdate([(0, 1), (0, 0), (2, 0)])
>>> # 1. (0, 1) overwrites (0, 0)             -> bidict({0: 1, 1: 2})
>>> # 2. (0, 0) overwrites (0, 1)             -> bidict({0: 0, 1: 2})
>>> # 3. (2, 0) overwrites (0, 0)             -> bidict({1: 2, 2: 0})
>>> sorted(b.items())  # different result
[(1, 2), (2, 0)]

Interop

bidicts interoperate well with other types of mappings. For example, they support (efficient) polymorphic equality testing:

>>> from bidict import bidict
>>> bidict(a=1) == dict(a=1)
True

And converting back and forth works as expected (modulo any value duplication, as discussed above):

>>> dict(bidict(a=1))
{'a': 1}
>>> bidict(dict(a=1))
bidict({'a': 1})

See the Polymorphism section for more interoperability documentation.

Hopefully bidict feels right at home among the Python built-ins you already know. Proceed to Other bidict Types for documentation on the remaining bidict flavors.