Changelog#

Sponsor

If you or your organization depends on bidict, please consider sponsoring bidict on GitHub.

Tip

Watch bidict releases on GitHub to be notified when new versions of bidict are published. Click the “Watch” dropdown, choose “Custom”, and then choose “Releases”.

0.23.1 (2024-02-18)#

Fix a regression in 0.23.0 that could defeat type inference of a bidict’s key type and value type when running in Python 3.8 or 3.9. #310

0.23.0 (2024-02-14)#

Primarily, this release simplifies bidict by removing minor features that are no longer necessary or that have little to no apparent usage, and it also includes some performance optimizations.

Specifically, initializing or updating a bidict is now up to 70% faster in microbenchmarks.

The changes in this release will also make it easier to maintain and improve bidict in the future, including further potential performance optimizations.

It also contains several other improvements.

  • Drop support for Python 3.7, which reached end of life on 2023-06-27, and take advantage of features available in Python 3.8+.

  • Remove FrozenOrderedBidict now that Python 3.7 is no longer supported. frozenbidict now provides everything that FrozenOrderedBidict provided (including reversibility) on all supported Python versions, but with less space overhead.

  • Remove namedbidict due to low usage.

  • Remove the kv field of OnDup which specified the OnDupAction to take in the case of Key and Value Duplication. The val field now specifies the action to take in the case of Key and Value Duplication as well as just value duplication.

  • Improve type hints for the inv shortcut alias for inverse.

  • Fix a bug where calls like bidict(None), bi.update(False), etc. would fail to raise a TypeError.

  • All __init__(), update(), and related methods now handle SupportsKeysAndGetItem objects that are not Mappings the same way that MutableMapping.update() does, before falling back to handling the provided object as an iterable of pairs.

  • The repr() of ordered bidicts now matches that of regular bidicts, e.g. OrderedBidict({1: 1}) rather than OrderedBidict([(1, 1)]).

    (Accordingly, the bidict.__repr_delegate__ field has been removed now that it’s no longer needed.)

    This tracks with the change to collections.OrderedDict's repr() in Python 3.12.

  • Test with Python 3.12 in CI.

    Note: Older versions of bidict also support Python 3.12, even though they don’t explicitly declare support for it.

  • Drop use of Trove classifiers that declare support for specific Python versions in package metadata.

0.22.1 (2022-12-31)#

  • Only include the source code in the source distribution. This reduces the size of the source distribution from ~200kB to ~30kB.

  • Fix the return type hint of bidict.inverted() to return an Iterator, rather than an Iterable.

0.22.0 (2022-03-23)#

  • Drop support for Python 3.6, which reached end of life on 2021-12-23 and is no longer supported by pip as of pip version 22. Take advantage of this to reduce bidict’s maintenance costs.

  • Use mypy-appeasing explicit re-exports in __init__.py (e.g. import x as x) so that mypy no longer gives you an implicit re-export error if you run it with --no-implicit-reexport (or --strict) against code that imports from bidict.

  • Update the implementations and type annotations of bidict.BidictBase.keys() and bidict.BidictBase.values() to make use of the new BidictKeysView type, which works a bit better with type checkers.

  • Inverse bidict instances are now computed lazily the first time the inverse attribute is accessed rather than being computed eagerly during initialization. (A bidict’s backing, inverse, one-way mapping is still kept in sync eagerly as any mutations are made, to preserve key- and value-uniqueness.)

  • Optimize initializing a bidict with another bidict. In a microbenchmark on Python 3.10, this now performs over 2x faster.

  • Optimize updating an empty bidict with another bidict. In a microbenchmark on Python 3.10, this now performs 60-75% faster.

  • Optimize copy(). In a microbenchmark on Python 3.10, this now performs 10-20x faster.

  • Optimize rolling back failed updates to a bidict in the case that the number of items passed to the update call can be determined to be larger than the bidict being updated. Previously this rollback was O(n) in the number of items passed. Now it is O(1), i.e. unboundedly faster.

  • Optimize bidict.BidictBase.__contains__() (the method called when you run key in mybidict). In a microbenchmark on Python 3.10, this now performs over 3-10x faster in the False case, and at least 50% faster in the True case.

  • Optimize bidict.BidictBase.__eq__() (the method called when you run mybidict == other). In a microbenchmark on Python 3.10, this now performs 15-25x faster for ordered bidicts, and 7-12x faster for unordered bidicts.

  • Optimize equals_order_sensitive(). In a microbenchmark on Python 3.10, this now performs 2x faster for ordered bidicts and 60-90% faster for unordered bidicts.

  • Optimize the MappingView objects returned by bidict.OrderedBidict.keys(), bidict.OrderedBidict.values, and bidict.OrderedBidict.items() to delegate to backing dict_keys and dict_items objects if available, which are much faster in CPython. For example, in a microbenchmark on Python 3.10, orderedbi.items() == d.items() now performs 30-50x faster.

  • Fix a bug where bidict.BidictBase.__eq__() was always returning False rather than NotImplemented in the case that the argument was not a Mapping, defeating the argument’s own __eq__() if implemented. As a notable example, bidicts now correctly compare equal to unittest.mock.ANY.

  • bidict.BidictBase now adds a __reversed__ implementation to subclasses that don’t have an overridden implementation depending on whether both their backing mappings are Reversible. Previously, a __reversed__ implementation was only added to BidictBase when BidictBase._fwdm_cls was Reversible. So if a BidictBase subclass set its _fwdm_cls to a non-reversible mutable mapping, it would also have to manually set its __reversed__ attribute to None to override the implementation inherited from BidictBase. This is no longer necessary thanks to bidict’s new object.__init_subclass__() logic.

  • The MappingView objects returned by bidict.OrderedBidict.keys(), bidict.OrderedBidict.values, and bidict.OrderedBidict.items() are now Reversible. (This was already the case for unordered bidicts when running on Python 3.8+.)

  • Add support for Python 3.9-style dict merge operators (PEP 584).

    See the tests for examples.

  • Update docstrings for bidict.BidictBase.keys(), bidict.BidictBase.values(), and bidict.BidictBase.items() to include more details.

  • namedbidict now exposes the passed-in keyname and valname in the corresponding properties on the generated class.

  • namedbidict now requires base_type to be a subclass of BidictBase, but no longer requires base_type to provide an _isinv attribute, which BidictBase subclasses no longer provide.

  • When attempting to pickle a bidict’s inverse whose class was dynamically generated, and no reference to the dynamically-generated class has been stored anywhere in sys.modules where pickle can find it, the pickle call is now more likely to succeed rather than failing with a PicklingError.

  • Remove the use of slots from (non-ABC) bidict types.

    This better matches the mapping implementations in Python’s standard library, and significantly reduces code complexity and maintenance burden. The memory savings conferred by using slots are not noticeable unless you’re creating millions of bidict instances anyway, which is an extremely unusual usage pattern.

    Of course, bidicts can still contain millions (or more) items (which is not an unusual usage pattern) without using any more memory than before these changes. Notably, slots are still used in the internal linked list nodes of ordered bidicts to save memory, since as many node instances are created as there are items inserted.

0.21.4 (2021-10-23)#

Explicitly declare support for Python 3.10 as well as some minor internal improvements.

0.21.3 (2021-09-05)#

  • All bidicts now provide the equals_order_sensitive() method, not just OrderedBidicts.

    Since support for Python < 3.6 was dropped in v0.21.0, dicts provide a deterministic ordering on all supported Python versions, and as a result, all bidicts do too. So now even non-Ordered bidicts might as well provide equals_order_sensitive().

    See the updated What about order-preserving dicts? docs for more info.

  • Take better advantage of the fact that dicts became reversible in Python 3.8.

    Specifically, now even non-Ordered bidicts provide a __reversed__() implementation on Python 3.8+ that calls reversed() on the backing _fwdm mapping.

    As a result, if you are using Python 3.8+, frozenbidict now gives you everything that FrozenOrderedBidict gives you, but with less space overhead.

  • Drop setuptools_scm as a setup_requires dependency.

  • Remove the bidict.__version_info__ attribute.

0.21.2 (2020-09-07)#

0.21.1 (2020-09-07)#

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

0.21.0 (2020-08-22)#

0.20.0 (2020-07-23)#

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 put() and putall().

  • The on_dup_key, on_dup_val, and on_dup_kv 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 collections.abc.Mapping. #111

0.19.0 (2020-01-09)#

  • Drop support for Python 2 as promised in v0.18.2.

    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 UserWarning will now be emitted if these are used.

    bidict.DROP_OLD and bidict.DROP_NEW should be used instead.

  • Rename DuplicationPolicy to OnDupAction (and implement it via an Enum).

    An OnDupAction may be one of RAISE, DROP_OLD, or DROP_NEW.

  • Expose the new OnDup class to contain the three OnDupActions that should be taken upon encountering the three kinds of duplication that can occur (key, val, kv).

  • Provide the ON_DUP_DEFAULT, ON_DUP_RAISE, and ON_DUP_DROP_OLD OnDup convenience instances.

  • Deprecate the on_dup_key, on_dup_val, and on_dup_kv arguments of put() and putall(). A UserWarning will now be emitted if these are used.

    These have been subsumed by the new on_dup argument, which takes an OnDup instance.

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

    The Values Must Be Unique docs have been updated accordingly.

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

    These have been subsumed by the new on_dup class attribute, which takes an OnDup instance.

    See the updated Extending bidict 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 dicts in the bidict types for which this is possible.

  • Move bidict.BidictBase.values() to bidict.BidirectionalMapping.values, since the implementation is generic.

  • No longer use __all__ in bidict’s __init__.py.

0.18.4 (2020-11-02)#

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

0.18.3 (2019-09-22)#

  • Improve validation of names passed to namedbidict: Use str.isidentifier() on Python 3, and a better regex on Python 2.

  • On Python 3, set __qualname__ on namedbidict classes based on the provided typename argument.

0.18.2 (2019-09-08)#

  • Warn that Python 2 support will be dropped in a future release when Python 2 is detected.

0.18.1 (2019-09-03)#

  • Fix a regression introduced by the memory optimizations added in 0.15.0 which caused deepcopied and unpickled bidicts to have their inverses set incorrectly. #94

0.18.0 (2019-02-14)#

  • Rename bidict.BidirectionalMapping.inv to inverse and make bidict.BidictBase.inv an alias for inverse. #86

  • bidict.BidirectionalMapping.__subclasshook__ now requires an inverse attribute rather than an inv attribute for a class to qualify as a virtual subclass. This breaking change is expected to affect few if any users.

  • Add Python 2/3-compatible bidict.compat.collections_abc alias.

  • Stop testing Python 3.4 on CI, and warn when Python 3 < 3.5 is detected rather than Python 3 < 3.3.

    Python 3.4 reaches end of life on 2019-03-18. As of January 2019, 3.4 represents only about 3% of bidict downloads on PyPI Stats.

0.17.5 (2018-11-19)#

Improvements to performance and delegation logic, with minor breaking changes to semi-private APIs.

  • Remove the __delegate__ instance attribute added in the previous release. It was overly general and not worth the cost.

    Instead of checking self.__delegate__ and delegating accordingly each time a possibly-delegating method is called, revert back to using “delegated-to-fwdm” mixin classes (now found in bidict._delegating_mixins), and resurrect a mutable bidict parent class that omits the mixins as bidict.MutableBidict.

  • Rename __repr_delegate__ to _repr_delegate.

0.17.4 (2018-11-14)#

Minor code, interop, and (semi-)private API improvements.

  • OrderedBidict optimizations and code improvements.

    Use bidicts for the backing _fwdm and _invm mappings, obviating the need to store key and value data in linked list nodes.

  • Refactor proxied- (i.e. delegated-) to-_fwdm logic for better composability and interoperability.

    Drop the _Proxied* mixin classes and instead move their methods into BidictBase, which now checks for an object defined by the BidictBase.__delegate__ attribute. The BidictBase.__delegate__ object will be delegated to if the method is available on it, otherwise a default implementation (e.g. inherited from Mapping) will be used otherwise. Subclasses may set __delegate__ = None to opt out.

    Consolidate _MutableBidict into bidict.bidict now that the dropped mixin classes make it unnecessary.

  • Change __repr_delegate__ to simply take a type like dict or list.

  • Upgrade to latest major sortedcontainers version (from v1 to v2) for the SortedBidict Recipes.

  • bidict.compat.{view,iter}{keys,values,items} on Python 2 no longer assumes the target object implements these methods, as they’re not actually part of the Mapping interface, and provides fallback implementations when the methods are unavailable. This allows the SortedBidict Recipes to continue to work with sortedcontainers v2 on Python 2.

0.17.3 (2018-09-18)#

  • Improve packaging by adding a pyproject.toml and by including more supporting files in the distribution. #81

  • Drop pytest-runner and support for running tests via python setup.py test in preference to pytest or python -m pytest.

0.17.2 (2018-04-30)#

Memory usage improvements

  • Use less memory in the linked lists that back OrderedBidicts by storing node data unpacked rather than in (key, value) tuple objects.

0.17.1 (2018-04-28)#

Bugfix Release

Fix a regression in 0.17.0 that could cause erroneous behavior when updating items of an OrderedBidict’s inverse, e.g. some_ordered_bidict.inv[foo] = bar.

0.17.0 (2018-04-25)#

Speedups and memory usage improvements

  • Pass keys(), values(), and items() calls (as well as their iter* and view* counterparts on Python 2) through to the backing _fwdm and _invm dicts so that they run as fast as possible (i.e. at C speed on CPython), rather than using the slower implementations inherited from collections.abc.Mapping.

  • Use weakrefs in the linked lists that back OrderedBidicts to avoid creating strong reference cycles.

    Memory for an ordered bidict that you create can now be reclaimed in CPython as soon as you no longer hold any references to it, rather than having to wait until the next garbage collection. #71

Misc

0.16.0 (2018-04-06)#

Minor code and efficiency improvements to inverted() and bidict._iter._iteritems_args_kw (formerly bidict.pairs()).

Minor Breaking API Changes

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

  • Rename bidict.pairs() → bidict._iter._iteritems_args_kw.

0.15.0 (2018-03-29)#

Speedups and memory usage improvements

  • Use __slots__ to speed up bidict attribute access and reduce memory usage. On Python 3, instantiating a large number of bidicts now uses ~57% the amount of memory that it used before, and on Python 2 only ~33% the amount of memory that it used before, in a simple but representative benchmark.

  • Use weakrefs to refer to a bidict’s inverse internally, no longer creating a strong reference cycle. Memory for a bidict that you create can now be reclaimed in CPython as soon as you no longer hold any references to it, rather than having to wait for the next garbage collection. See the new bidict Avoids Reference Cycles documentation. #24

  • Make bidict.BidictBase.__eq__() significantly more speed- and memory-efficient when comparing to a non-dict Mapping. (Mapping.__eq__()'s inefficient implementation will now never be used.) The implementation is now more reusable as well.

  • Make bidict.OrderedBidictBase.__iter__() as well as equality comparison slightly faster for ordered bidicts.

Minor Bugfixes

  • namedbidict now verifies that the provided keyname and valname are distinct, raising ValueError if they are equal.

  • namedbidict now raises TypeError if the provided base_type is not a BidirectionalMapping.

  • If you create a custom bidict subclass whose _fwdm_cls differs from its _invm_cls (as in the FwdKeySortedBidict example from the SortedBidict Recipes), the inverse bidirectional mapping type (with _fwdm_cls and _invm_cls swapped) is now correctly computed and used automatically for your custom bidict’s inverse bidict.

Misc

  • Classes no longer have to provide an __inverted__ attribute to be considered virtual subclasses of BidirectionalMapping.

  • If bidict.inverted() is passed an object with an __inverted__ attribute, it now ensures it is callable() before returning the result of calling it.

  • __repr__() no longer checks for a __reversed__ method to determine whether to use an ordered or unordered-style repr. It now calls the new __repr_delegate__ instead (which may be overridden if needed), for better composability.

Minor Breaking API Changes

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

  • Split back out the BidictBase class from frozenbidict and OrderedBidictBase from FrozenOrderedBidict, reverting the merging of these in 0.14.0. Having e.g. issubclass(bidict, frozenbidict) == True was confusing, so this change restores issubclass(bidict, frozenbidict) == False.

    See the updated Bidict Types Diagram and Polymorphism documentation.

  • Rename:

    • bidict.BidictBase.fwdm → ._fwdm

    • bidict.BidictBase.invm → ._invm

    • bidict.BidictBase.fwd_cls → ._fwdm_cls

    • bidict.BidictBase.inv_cls → ._invm_cls

    • bidict.BidictBase.isinv → ._isinv

    Though overriding _fwdm_cls and _invm_cls remains supported (see Extending bidict), this is not a common enough use case to warrant public names. Most users do not need to know or care about any of these.

  • The RAISE, OVERWRITE, and IGNORE duplication policies are no longer available as attributes of DuplicationPolicy, and can now only be accessed as attributes of the bidict module namespace, which was the canonical way to refer to them anyway. It is now no longer possible to create an infinite chain like DuplicationPolicy.RAISE.RAISE.RAISE...

  • Make bidict.pairs() and bidict.inverted() no longer importable from bidict.util, and now only importable from the top-level bidict module. (bidict.util was renamed bidict._util.)

  • Pickling ordered bidicts now requires at least version 2 of the pickle protocol. If you are using Python 3, pickle.DEFAULT_PROTOCOL is 3 anyway, so this will not affect you. However if you are using in Python 2, DEFAULT_PROTOCOL is 0, so you must now explicitly specify the version in your pickle.dumps() calls, e.g. pickle.dumps(ob, 2).