diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 5762c11..5748060 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -10,14 +10,21 @@ Release Notifications to automatically be notified via email when a new version of bidict is released. -0.12.0-dev (not yet released) ------------------------------ +0.12.0 (2016-07-03) +------------------- + +- New/renamed exceptions: + + - :class:`KeyDuplicationError ` + - :class:`ValueDuplicationError ` + - :class:`KeyAndValueDuplicationError ` + - :class:`DuplicationError ` (base class for the above) - :func:`put() ` now accepts ``on_dup_key``, ``on_dup_val``, and ``on_dup_kv`` keyword args which allow you to override the default behavior - when the key and/or value of a given item - duplicate those/that of any existing item(s). + when the key or value of a given item + duplicates that (those) of any existing item(s). These can take the following values: - :attr:`bidict.DuplicationBehavior.RAISE` @@ -28,36 +35,40 @@ when a new version of bidict is released. If not provided, :func:`put() ` uses - :attr:`RAISE ` behavior default. + :attr:`RAISE ` behavior by default. - New :func:`putall() ` method - provides a bulk :func:`put() ` API. + provides a bulk :func:`put() ` API, + allowing you to override the default duplication handling behavior + that :func:`update() ` uses. -- :func:`bidict.update() ` now offers stronger - consistency guarantees by checking for and handling duplication - before inserting any of the given items. - So if an :func:`update() ` call causes a - :class:`ValueDuplicationError `, - you can now be sure that none of the given items were inserted. +- :func:`bidict.update() ` now fails clean, + so if an :func:`update() ` call raises a + :class:`DuplicationError `, + you can now be sure that none of the given items was inserted. - Previously, any of the given items that were processed + Previously, all of the given items that were processed before the one causing the failure would have been inserted, - and there was no good way to recover which were inserted - and which had yet to be inserted at the time of the error, - nor to undo the partial insertion after finding out - not all items could be inserted. + and no facility was provided to recover + which items were inserted and which weren't, + nor to revert any changes made by the failed + :func:`update() ` call. The new behavior makes it easier to reason about and control - the effects of bulk insert operations. - This is known as "fail clean" behavior. + the effects of failed :func:`update() ` calls. The new :func:`putall() ` method also fails clean. -- New exceptions: + Internally, this is implemented by storing a log of changes + made while an update is being processed, and rolling back the changes + when one of them is found to cause an error. + This required reimplementing :class:`orderedbidict ` + on top of two dicts and a linked list, rather than two OrderedDicts, + since :class:`OrderedDict ` does not expose + its underlying linked list. - - :class:`KeyDuplicationError ` - - :class:`ValueDuplicationError ` - - :class:`KeyAndValueDuplicationError ` - - :class:`DuplicationError ` (base class for the above) +- :func:`orderedbidict.move_to_end() ` + now works on Python < 3.2 as a result of the new + :class:`orderedbidict ` implementation. - Add @@ -73,23 +84,14 @@ when a new version of bidict is released. :func:`viewitems() ` compatibility helpers. -- Implement several functions more efficiently - (including +- More efficient implementations of :func:`pairs() `, :func:`inverted() `, and - :func:`bidict.copy() `). + :func:`bidict.copy() `. -- Implement :func:`bidict.BidirectionalMapping.__copy__` +- Implement :func:`bidict.__copy__() ` for use with the :mod:`copy` module. -- When overwriting the key of an existing value in an - :class:`bidict.orderedbidict`, the position of the existing item is - now preserved rather than being moved to the end, which matches the - behavior of preserving order when overwriting the value of an existing key. - -- :func:`orderedbidict.move_to_end ` - now works on Python < 3.2. - - Fix issue preventing a client class from inheriting from :class:`loosebidict ` (see `#34 `_). @@ -102,8 +104,36 @@ when a new version of bidict is released. Breaking API Changes ^^^^^^^^^^^^^^^^^^^^ -- Rename ``KeyExistsException`` :class:`KeyDuplicationError ` - and ``ValueExistsException`` :class:`ValueDuplicationError `. +- Rename ``KeyExistsException`` to :class:`KeyDuplicationError ` + and ``ValueExistsException`` to :class:`ValueDuplicationError `. + +- When overwriting the key of an existing value in an :class:`orderedbidict `, + the position of the existing item is now preserved, + overwriting the key of the existing item in place, + rather than moving the item to the end. + This now matches the behavior of overwriting the value of an existing key, + which has always preserved the position of the existing item. + (If inserting an item whose key duplicates that of one existing item + and whose value duplicates that of another, + the existing item whose value is duplicated is still dropped, + and the existing item whose key is duplicated + still gets its value overwritten in place, as before.) + + For example:: + + >>> from bidict import orderedbidict + >>> o = orderedbidict([(0, 1), (2, 3)]) + >>> o.forceput(4, 1) + + previously would have resulted in:: + + >>> o # doctest: +SKIP + orderedbidict([(2, 3), (4, 1)]) + + but now results in:: + + >>> o + orderedbidict([(4, 1), (2, 3)]) 0.11.0 (2016-02-05) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 06dd32d..3b6b235 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -135,9 +135,9 @@ Code of Conduct --------------- All participation in this project should respect the -:doc:`Code of Conduct ` -(`<./CODE_OF_CONDUCT.rst>`_ | -``_). +:doc:`Code of Conduct `. +(If that link does not work, see ``CODE_OF_CONDUCT.rst`` or +``_.) By participating, you are expected to honor this code. Thanks diff --git a/README.rst b/README.rst index dfea2a9..10dde05 100644 --- a/README.rst +++ b/README.rst @@ -3,11 +3,11 @@ bidict Efficient, Pythonic bidirectional map implementation and related functionality. -.. image:: ./_static/logo-256.png +.. image:: https://raw.githubusercontent.com/jab/bidict/master/_static/logo-256.png :target: https://bidict.readthedocs.io/ :alt: bidict logo -.. image:: ./_static/support-on-gumroad.png +.. image:: https://raw.githubusercontent.com/jab/bidict/master/_static/support-on-gumroad.png :target: https://gumroad.com/l/bidict :alt: Support bidict @@ -29,7 +29,7 @@ Status :alt: Follow on VersionEye .. image:: https://readthedocs.org/projects/bidict/badge/?version=master - :target: https://bidict.readthedocs.io/en/master + :target: https://bidict.readthedocs.io/en/master/ :alt: Documentation .. image:: https://travis-ci.org/jab/bidict.svg?branch=master @@ -74,7 +74,7 @@ Installation Usage ----- -For usage documentation, please start at the :ref:`intro` +For usage documentation, please start at the Introduction and proceed from there. `bidict.readthedocs.io `_ @@ -91,7 +91,7 @@ and by default you will be taken to the version built from the master branch. You can choose different versions from the pop-up menu in the lower-right.* You can also build the docs yourself by running ``make html`` -from the ``_ directory +from the ``docs`` directory (requires `Sphinx `_). @@ -100,13 +100,13 @@ Contributing Contributions are gratefully received! For information about contributing, -please see :ref:`contributing` -(`<./CONTRIBUTING.rst>`_ | ``_). +please see CONTRIBUTING.rst +(``_). Changelog --------- For a history of notable changes to bidict, -check out the :ref:`changelog` -(`<./CHANGELOG.rst>`_ | ``_). +check out CHANGELOG.rst +(``_). diff --git a/_static/custom.css b/_static/custom.css new file mode 100644 index 0000000..5e78db3 --- /dev/null +++ b/_static/custom.css @@ -0,0 +1,6 @@ +/* override + * https://github.com/bitprophet/alabaster/blob/7e8ee8/alabaster/static/alabaster.css_t#L609-L611 + */ +div#changelog > div.section > ul > li > p:only-child { + margin-bottom: 17px; +} diff --git a/bidict/VERSION b/bidict/VERSION index 367cb97..ac454c6 100644 --- a/bidict/VERSION +++ b/bidict/VERSION @@ -1 +1 @@ -0.12.0.dev +0.12.0