better document divergence from dict, misc. suggestions

[jab]

First off, I just discovered this library – very cool! (I'm the author of https://github.com/jab/bidict so am particularly interested in other Mapping implementations. [1])

I noticed the README says

The Map object implements collections.abc.Mapping ABC so working with it is very similar to working with Python dicts.

The only exception are its Map.set() and Map.delete() methods which return a new instance of Map

But right off the bat I noticed some additional discrepancies that seem worth documenting:

• If you pass items via *args and/or **kwargs into the Map(...) initializer they're ignored?

In [37]: Map([(1, 2), (3, 4)])
Out[37]: <immutables.Map({}) at 0x107788ea0>

In [38]: Map({1: 2, 3: 4})
Out[38]: <immutables.Map({}) at 0x107788ea0>

In [39]: Map(one=1, two=2)
Out[39]: <immutables.Map({}) at 0x107788ea0>

• map.get('missing') does not raise KeyError as dict.get('missing') does, but rather behaves like dict.get('missing', default=None)

Are these bugs or are they intentional? If intentional, I think these are significantly divergent enough to warrant documenting.

Other suggestions

• add an update() method that returns a new Map based on the current one with the provided items set
• add an immutables.__version__ attribute

[1] I was immediately curious to see what it would take to implement an alternate version of frozenbidict that used immutables.Map for the backing forward and inverse maps, but the divergence from dict.__init__() and dict.get() made me hesitate. I still might put together a recipe for https://bidict.readthedocs.io/extending.html though if I come up with something useful after playing with it some more.

[1st1]

If you pass items via *args and/or **kwargs into the Map(...) initializer they're ignored?

This is a bug! It shouldn't allow you to pass anything.

map.get('missing') does not raise KeyError as dict.get('missing') does, but rather behaves like dict.get('missing', default=None)

dict.get('missing') doesn't raise an error:

>>> a = {}
>>> a.get('missing')
>>>

add an update() method that returns a new Map based on the current one with the provided items set

Yes, that's something we'll need to add support for soon.

[Tinche]

This is a bug! It shouldn't allow you to pass anything.

If you ask me, having the initializer mimic the dict initializer would be the way to go. Bonus points if it can be made more efficient than making x intermediate maps.

[1st1]

If you ask me, having the initializer mimic the dict initializer would be the way to go.

Sure, but right now initializers are not supported so it's a bug that they are accepted. Implementing initializers support properly isn't trivial.