From e00344e0c18742108e479cf6e6a701914f945bf8 Mon Sep 17 00:00:00 2001 From: Joshua Bronson Date: Thu, 21 Oct 2021 22:00:48 +0000 Subject: [PATCH] Minor docs improvements. --- bidict/_frozenordered.py | 13 ++++++++++- docs/other-bidict-types.rst | 45 +++++++++++++++++++++++-------------- 2 files changed, 40 insertions(+), 18 deletions(-) diff --git a/bidict/_frozenordered.py b/bidict/_frozenordered.py index ef5aecb..04725ea 100644 --- a/bidict/_frozenordered.py +++ b/bidict/_frozenordered.py @@ -35,7 +35,18 @@ from ._typing import KT, VT class FrozenOrderedBidict(OrderedBidictBase[KT, VT]): - """Hashable, immutable, ordered bidict type.""" + """Hashable, immutable, ordered bidict type. + + Like a hashable :class:`bidict.OrderedBidict` + without the mutating APIs, or like a + reversible :class:`bidict.frozenbidict` even on Python < 3.8. + (All bidicts are order-preserving when never mutated, so frozenbidict is + already order-preserving, but only on Python 3.8+, where dicts are + reversible, are all bidicts (including frozenbidict) also reversible.) + + If you are using Python 3.8+, frozenbidict gives you everything that + FrozenOrderedBidict gives you, but with less space overhead. + """ __slots__ = ('_hash',) __hash__ = frozenbidict.__hash__ diff --git a/docs/other-bidict-types.rst b/docs/other-bidict-types.rst index 309220c..e8700ab 100644 --- a/docs/other-bidict-types.rst +++ b/docs/other-bidict-types.rst @@ -71,10 +71,10 @@ API documentation for more information. ------------------------------ :class:`bidict.OrderedBidict` -is a mutable :class:`~bidict.BidirectionalMapping` +is a :class:`~bidict.MutableBidirectionalMapping` that preserves the ordering of its items, and offers some additional ordering-related APIs -that non-:class:`Ordered ` bidicts can't offer. +that non-ordered bidicts can't offer. It's like a bidirectional version of :class:`collections.OrderedDict`. .. doctest:: @@ -96,7 +96,7 @@ It's like a bidirectional version of :class:`collections.OrderedDict`. >>> last_item ('Be', 'beryllium') -Additional ordering-related APIs +Additional ordering-related, mutating APIs modeled after :class:`~collections.OrderedDict`, e.g. :meth:`popitem(last=False) ` and :meth:`~bidict.OrderedBidict.move_to_end`, @@ -203,9 +203,12 @@ What about order-preserving dicts? In PyPy as well as CPython 3.6+, :class:`dict` preserves insertion order. Given that, can you get away with -using a non-:class:`Ordered ` :class:`bidict.bidict` +using a non-ordered bidict in places where you need -an order-preserving bidirectional mapping? +an order-preserving bidirectional mapping +(assuming you don't need the additional ordering-related, mutating APIs +offered by :class:`~bidict.OrderedBidict` +like :meth:`~bidict.OrderedBidict.move_to_end`)? Consider this example: @@ -224,22 +227,25 @@ Consider this example: OrderedBidict([(-1, 1), ('UPDATED', 2), (-3, 3)]) When the value associated with the key ``2`` -in the non-:class:`Ordered ` bidict ``b`` was changed, +in the non-ordered bidict ``b`` was changed, the corresponding item stays in place in the forward mapping, but moves to the end of the inverse mapping. -Since non-:class:`Ordered ` :class:`~bidict.bidict`\s +Since non-ordered bidicts provide weaker ordering guarantees (which allows for a more efficient implementation), it's possible to see behavior like in the example above after certain sequences of mutations. That said, if you depend on preserving insertion order, -a non-:class:`Ordered ` bidict may be sufficient if: +a non-ordered bidict may be sufficient if: -* you're never mutating it, or +* you'll never mutate it + (in which case, use a :class:`~bidict.frozenbidict`), + or: -* you're only mutating by removing and/or adding whole new items, - never changing just the key or value of an existing item, or +* you only mutate by removing and/or adding whole new items, + never changing just the key or value of an existing item, + or: * you're only changing existing items in the forward direction (i.e. changing values by key, rather than changing keys by value), @@ -247,14 +253,19 @@ a non-:class:`Ordered ` bidict may be sufficient if: not the order of the items in its inverse. On the other hand, if your code is actually depending on the order, -using an :meth:`~bidict.OrderedBidict` makes for clearer code. +using an ordered bidict explicitly makes for clearer code. -This will also give you additional order-specific APIs, such as +:class:`~bidict.OrderedBidict` also gives you +additional ordering-related mutating APIs, such as :meth:`~bidict.OrderedBidict.move_to_end` and -:meth:`popitem(last=False) `. -(And also -:meth:`~bidict.OrderedBidict.__reversed__` on Python < 3.8. -On Python 3.8+, all bidicts are :class:`reversible `.) +:meth:`popitem(last=False) `, +should you ever need them. + +(And on Python < 3.8, +:class:`~bidict.OrderedBidict` also gives you +:meth:`~bidict.OrderedBidict.__reversed__`. +On Python 3.8+, all bidicts are :class:`reversible ` +as of :ref:`v0.21.3 `.) :class:`~bidict.FrozenOrderedBidict`