Add BidirectionalDict recipe to `collections`

[nineteendo]

Documentation

Originally suggested by @picnixz's comment, recipe by me:

class BidirectionalDict(UserDict):
    def __init__(self, *args, **kwargs):
        self.inverse_data = {}
        super().__init__(*args, **kwargs)

    def __setitem__(self, key, value):
        if key in self.data:
            if value == (old_value := self.data[key]):
                return

            del self.inverse_data[old_value]

        if value in self.inverse_data:
            raise ValueError("Duplicate value")

        self.data[key] = value
        self.inverse_data[value] = key

    def __delitem__(self, key):
        value = self.data[key]
        del self.data[key]
        del self.inverse_data[value]

    @property
    def inverse(self):
        inverse_bidict = BidirectionalDict()
        inverse_bidict.data = self.inverse_data
        inverse_bidict.inverse_data = self.data
        return inverse_bidict

[picnixz]

My suggestion about the recipes was to first have a recipe-like page for collections itself. Currently, no such page exists but I don't know if @rhettinger would be willing to have a recipe page for this module. As for the above recipe, I'm not sure if a recipe based on UserDict and not inheriting collections.abc.Mapping instead is preferrable or not with two explicit internal dicts and an explicit interface (same as Guava's BiMap)

[nineteendo]

Well, can't we just add it as a UserDict recipe like the other recipes?

• ChainMap Examples and Recipes
• deque Recipes
• OrderedDict Examples and Recipes

As for inheriting from UserDict:

• the implementation is easier (no need to implement __getitem__, __iter__ and __len__)
• it implements more methods for us: __repr__, __or__, __ror__, __ior__, __copy__, copy and fromkeys

It also serves as an excellent example how flexible UserDict is.

[picnixz]

• fromkeys wouldn't be helpful because you have one value mapped to multiple keys. So in a bimap, this would cause a "duplicated value error".
• I missed the recipes section, my bad.

[rhettinger]

If someone wants a bidirectional dictionary, they should pip install a mature, well documented tool such as: https://github.com/jab/bidict.

Also, I don't think this is suitable as a "recipe". There are many possible implementation strategies and APIs. It isn't the job of the docs to choose between those. It isn't even clear that a class based solution is any better than what most people typically do with two simple dictionaries and a dual update.

ActiveState used to maintain a cookbook site where people like us would post snippets like this. It would be if great another website arose to take its place. I made many submissions there, things that would be interesting to some people but not worthy of being in the core documentation. Otherwise we don't really have a place to put these one-off examples other than personal gists or stackoverflow entries.