Bidict

-------------------

- Include `py.typed <https://www.python.org/dev/peps/pep-0561/#packaging-type-information>`__
file to mark :mod:`bidict` as type hinted.

-------------------

This release was yanked and replaced with the 0.21.2 release,
which actually provides the intended changes.

-------------------

- :mod:`bidict` now provides
`type hints <https://www.python.org/dev/peps/pep-0484/>`__! ⌨️ ✅

Adding type hints to :mod:`bidict` poses particularly interesting challenges
due to the combination of generic types,
dynamically-generated types
(such as :ref:`inverse bidict classes <extending:Dynamic Inverse Class Generation>`
and ``namedbidict``\s),
and complicating optimizations
such as the use of slots and weakrefs.

It didn't take long to hit bugs and missing features
in the state of the art for type hinting in Python today,
e.g. missing higher-kinded types support
(`python/typing548 <https://github.com/python/typing/issues/548#issuecomment-621195693>`__),
too-narrow type hints for :class:`collections.abc.Mapping`
(`python/typeshed4435 <https://github.com/python/typeshed/issues/4435>`__),
a :class:`typing.Generic` bug in Python 3.6
(`BPO-41451 <https://bugs.python.org/issue41451>`__), etc.

That said, this release should provide a solid foundation
for code using :mod:`bidict` that enables static type checking.

As always, if you spot any opportunities to improve :mod:`bidict`
(including its new type hints),
please don't hesitate to submit a PR!

- Add :class:`bidict.MutableBidirectionalMapping` ABC.

The :ref:`other-bidict-types:Bidict Types Diagram` has been updated accordingly.

- Drop support for Python 3.5,
which reaches end of life on 2020-09-13,
represents a tiny percentage of bidict downloads on
`PyPI Stats <https://pypistats.org/packages/bidict>`__,
and lacks support for
`variable type hint syntax <https://www.python.org/dev/peps/pep-0526/>`__,
`ordered dicts <https://stackoverflow.com/a/39980744>`__,
and :attr:`object.__init_subclass__`.

- Remove the no-longer-needed ``bidict.compat`` module.

- Move :ref:`inverse bidict class access <extending:Dynamic Inverse Class Generation>`
from a property to an attribute set in
:attr:`~bidict.BidictBase.__init_subclass__`,
to save function call overhead on repeated access.

- :meth:`bidict.OrderedBidictBase.__iter__` no longer accepts
a ``reverse`` keyword argument so that it matches the signature of
:meth:`container.__iter__`.

- Set the ``__module__`` attribute of various :mod:`bidict` types
(using :func:`sys._getframe` when necessary)
so that private, internal modules are not exposed
e.g. in classes' repr strings.

- ``namedbidict`` now immediately raises :class:`TypeError`
if the provided ``base_type`` does not provide
``_isinv`` or :meth:`~object.__getstate__`,
rather than succeeding with a class whose instances may raise
:class:`AttributeError` when these attributes are accessed.

-------------------

The following breaking changes are expected to affect few if any users.

Remove APIs deprecated in the previous release:

- ``bidict.OVERWRITE`` and ``bidict.IGNORE``.

- The ``on_dup_key``, ``on_dup_val``, and ``on_dup_kv`` arguments of
:meth:`~bidict.MutableBidict.put` and :meth:`~bidict.MutableBidict.putall`.

- The ``on_dup_key``, ``on_dup_val``, and ``on_dup_kv``
:class:`~bidict.bidict` class attributes.

- Remove ``bidict.BidirectionalMapping.__subclasshook__``
due to lack of use and maintenance cost.

Fixes a bug introduced in 0.15.0
that caused any class with an ``inverse`` attribute
to be incorrectly considered a subclass of :class:`collections.abc.Mapping`.
:issue:`111`

-------------------

- Drop support for Python 2
:ref:`as promised in v0.18.2 <changelog:0.18.2 (2019-09-08)>`.

The ``bidict.compat`` module has been pruned accordingly.

This makes bidict more efficient on Python 3
and enables further improvement to bidict in the future.

- Deprecate ``bidict.OVERWRITE`` and ``bidict.IGNORE``.
A :class:`UserWarning` will now be emitted if these are used.

:attr:`bidict.DROP_OLD` and :attr:`bidict.DROP_NEW` should be used instead.

- Rename ``DuplicationPolicy`` to :class:`~bidict.OnDupAction`
(and implement it via an :class:`~enum.Enum`).

An :class:`~bidict.OnDupAction` may be one of
:attr:`~bidict.RAISE`,
:attr:`~bidict.DROP_OLD`, or
:attr:`~bidict.DROP_NEW`.

- Expose the new :class:`~bidict.OnDup` class
to contain the three :class:`~bidict.OnDupAction`\s
that should be taken upon encountering
the three kinds of duplication that can occur
(*key*, *val*, *kv*).

- Provide the
:attr:`~bidict.ON_DUP_DEFAULT`,
:attr:`~bidict.ON_DUP_RAISE`, and
:attr:`~bidict.ON_DUP_DROP_OLD`
:class:`~bidict.OnDup` convenience instances.

- Deprecate the
``on_dup_key``, ``on_dup_val``, and ``on_dup_kv`` arguments
of :meth:`~bidict.MutableBidict.put` and :meth:`~bidict.MutableBidict.putall`.
A :class:`UserWarning` will now be emitted if these are used.

These have been subsumed by the new *on_dup* argument,
which takes an :class:`~bidict.OnDup` instance.

Use it like this: ``bi.put(1, 2, OnDup(key=RAISE, val=...))``.
Or pass one of the instances already provided,
such as :attr:`~bidict.ON_DUP_DROP_OLD`.
Or just don't pass an *on_dup* argument
to use the default value of :attr:`~bidict.ON_DUP_RAISE`.

The :ref:`basic-usage:Values Must Be Unique` docs
have been updated accordingly.

- Deprecate the
``on_dup_key``, ``on_dup_val``, and ``on_dup_kv``
:class:`~bidict.bidict` class attributes.
A :class:`UserWarning` will now be emitted if these are used.

These have been subsumed by the new
:attr:`~bidict.BidictBase.on_dup` class attribute,
which takes an :class:`~bidict.OnDup` instance.

See the updated :doc:`extending` docs for example usage.

- Improve the more efficient implementations of
``bidict.BidirectionalMapping.keys``,
``bidict.BidirectionalMapping.values``, and
``bidict.BidirectionalMapping.items``,
and now also provide a more efficient implementation of
``bidict.BidirectionalMapping.__iter__``
by delegating to backing :class:`dict`\s
in the bidict types for which this is possible.

- Move
:meth:`bidict.BidictBase.values` to
``bidict.BidirectionalMapping.values``,
since the implementation is generic.

- No longer use ``__all__`` in :mod:`bidict`'s ``__init__.py``.

-------------------

- Backport fix from v0.20.0
that removes ``bidict.BidirectionalMapping.__subclasshook__``
due to lack of use and maintenance cost.