About Site Map Submit Contact Us Log in | Create an account
Create an account Log In
Average Rating
User Rating:
Visitors Rating:
My rating:

Write review
See full specifications

linux default iconbidict Publisher's description

Bidirectional (one-to-one) mapping data structure

bidict is a Python package that provides a bidirectional mapping data structure and related utilities (namedbidict, inverted) to naturally model one-to-one relations in Python. To keep the learning curve low, it introduces no new functions to the dict API you're already familiar with. It owes its simplicity to Python's slice syntax, which provides a handy and natural way of expressing the inverse mapping in a bidict:

>>> husbands2wives = bidict({'john': 'jackie'})
>>> husbands2wives['john'] # the forward mapping is just like with dict
>>> husbands2wives[:'jackie'] # use slice for the inverse mapping

You can also use the unary inverse operator ~ on a bidict to get the inverse mapping:

>>> ~husbands2wives
bidict({'jackie': 'john'})

Motivation & More Examples

Python's built-in dict lets us associate unique keys with arbitrary values. Because keys must be hashable, values can be looked up by key in constant time. Different keys can map to the same value, but a single key cannot map to two different values. For instance, {-1: 1, 0: 0, 1: 1} is a dict with three unique keys and two unique values, because the keys -1 and 1 both map to 1. If you try to write its inverse {1: -1, 0: 0, 1: 1}, the dict that comes out has only two mappings, one for key 1 and one for key 0; since key 1 is not allowed to map to both -1 and 1, one of these mappings is discarded.

Sometimes the relation we're modeling will only ever have a single key mapping to a single value, as in the relation of husbands to wives (assuming monogamy). This is called a one-to-one (or injective) mapping (see http://en.wikipedia.org/wiki/Injective_mapping).

In this case we can be sure that the inverse mapping has the same number of items as the forward mapping, and moreover that if key k maps to value v in the forward mapping, value v maps to key k in the inverse. It would be useful then to be able to look up keys by value in constant time in addition to being able to look up values by key. With the additional constraint that values must be hashable as well as keys, just such a bidirectional dictionary is possible: enter bidict.

bidict provides a bidirectional mapping data structure which offers constant-time forward and inverse lookups in a syntax which builds naturally on what we're already used to from regular dicts. Consider the following one-to-one mapping:

>>> h2w = bidict({'bill': 'hillary', 'barack': 'michelle'})

To look up a wife by husband, use the familiar subscript syntax as with a dict:

>>> h2w['bill']

Or, by analogy to array slicing, you can optionally provide a trailing colon to emphasize that you're talking about a forward mapping:

>>> h2w['bill':]

And now you can guess how to spell the inverse mapping (i.e. to look up a husband by wife):

>>> h2w[:'hillary']

The slice syntax works for setting and deleting items in either direction too:

>>> h2w['bill':] = 'melinda'
>>> h2w[:'cher'] = 'sonny'
>>> del h2w[:'michelle']

The namedbidict class factory can be used to create a bidirectional mapping with customized names for the forward and the inverse mappings accessible via attributes.

A real-world example can be found in the htmlentitydefs module, which maintains a name2codepoint dict and an inverse codepoint2name dict separately. This could instead be modeled with a single bidict:

>>> HTMLEntities = namedbidict('HTMLEntities', 'names', 'codepoints')
>>> entities = HTMLEntities({'lt': 60, 'gt': 62, 'amp': 38}) # etc
>>> entities.names['lt']
>>> entities.codepoints[38]

See the bidict class for more examples.

Note: bidict does not subclass dict, but its API is a superset of the dict API minus the fromkeys method, which does not make sense in the context of an injective mapping. bidict implements the MutableMapping interface.

This module also provides an inverted iterator in the spirit of the built-in reversed. Pass in a mapping to get the inverse mapping, an iterable of pairs to get the pairs' inverses, or any object implementing an __inverted__ method. See the inverted class for examples.

Note: "inverse" rather than "reverse" is used because it's the term used in mathematics and its meaning is more specific, and because "reversed" already means something different in Python (reversing the order of the items in a sequence versus inverting the (k, v) pairs in a mapping).


System Requirements:

В· Python
Program Release Status:
Program Install Support: Install and Uninstall

bidict Tags:

Click on a tag to find related softwares

Is bidict your software?

Manage your software

Most Popular

linux default icon GDB 7.4
GDB, the GNU Project debugger, allows you to see what is going on `inside' another program while it... Read more
linux default icon Coral 0.9.1
Coral is a tool and a development platform to create and transform models and modeling languages.
linux default icon Forum Paid Plus Script 6.1
Forum Paid Pay Per Post Exchange is targeted at forum owners who wish to...
linux default icon sdo 0.6.5
Converts oracle SDO_GEOMETRY objects to WKT and GeoJSON.
linux default icon Get Paid Plus Script 6.1
Get Paid Plus Script

Related Category

» Other (877)
» Tools & Editors (359)
» Web Development (146)