Update docs

Author: nvictus

CHANGES

@@ -4,16 +4,14 @@ Release Notes
 1.4.0 (2024-02-14)
 ++++++++++++++++++
 
-What's changed:
-
-* The deprecated module-level ``minpq`` and ``maxpq`` have been removed in favor of same-named classmethods introduced in v1.3.0 (#24)
-* Introduce a distinct ``Empty`` exception for operations that attempt to remove items from an empty pqdict, instead of raising a ``KeyError``. (Note that ``Empty`` is derived from ``KeyError`` for subclass compatibility with ``Mapping.popitem`` and ``Mapping.clear``.) (#24)
-* Make internal heap nodes immutable and fast copy as originally proposed by @palkeo in #14
-
-Maintenance:
+* API changes:
+	- The deprecated module-level ``minpq`` and ``maxpq`` have been removed in favor of same-named classmethods introduced in v1.3.0 (#24)
+	- Introduce a distinct ``Empty`` exception for operations that attempt to remove items from an empty pqdict, instead of raising a ``KeyError``. (Note that ``Empty`` is derived from ``KeyError`` for subclass compatibility with ``Mapping.popitem`` and ``Mapping.clear``.) (#24)
+	- Make internal heap nodes immutable and fast copy as originally proposed by @palkeo in #14
 
-* Factored out indexed heap operations to reduce redundancy
-* Better docstrings and type annotations
+* Maintenance:
+	- Factored out indexed heap operations to reduce redundancy
+	- Better docstrings and type annotations
 
 **Full Changelog**: https://github.com/nvictus/pqdict/compare/v1.3.0...v1.4.0
 

README.rst

@@ -14,17 +14,16 @@ A priority queue dictionary maps hashable objects (keys) to priority-determining
 .. image:: https://img.shields.io/pypi/v/pqdict.svg
     :target: https://pypi.python.org/pypi/pqdict
 
-The priority queue is implemented as a binary heap of (key, priority value)
-pairs, which supports:
+The priority queue itself is implemented as a binary heap of (key, priority value) elements, which supports:
 
 - O(1) search for the item with highest priority
 
 - O(log n) removal of the item with highest priority
 
 - O(log n) insertion of a new item
 
-Additionally, an index maps elements to their location in the heap and is kept
-up to date as the heap is manipulated. As a result, pqdict also supports:
+Additionally, an index maps each key to its element's location in the heap and is kept
+up to date as the heap is manipulated. As a result, ``pqdict`` also supports:
 
 - O(1) lookup of any item by key
 
@@ -36,7 +35,7 @@ up to date as the heap is manipulated. As a result, pqdict also supports:
 Documentation
 -------------
 
-Documentation is available at http://pqdict.readthedocs.org/en/latest/.
+Documentation is available at http://pqdict.readthedocs.org/.
 
 
 License 

docs/intro.rst

@@ -4,17 +4,17 @@ Quickstart
 What is an "indexed" priority queue?
 ------------------------------------
 
-A `priority queue <http://en.wikipedia.org/wiki/Priority_queue>`__ allows you to serve or retrieve items in a prioritized fashion. A priority queue supports inserting elements with priorities, and removing or peeking at the top priority element. The vanilla priority queue interface can be extended to support random access, insertion, removal and changing the priority of any element in the queue. An *indexed* priority queue does these latter operations efficiently.
+A `priority queue <http://en.wikipedia.org/wiki/Priority_queue>`__ allows you to serve or retrieve items in a prioritized fashion. A priority queue supports inserting elements with priorities, and removing or peeking at the top priority element. The vanilla priority queue interface can be extended to support **random access to any element** as well as **removing or changing the priority of any element** in the queue. An *indexed* priority queue does these latter operations efficiently. 
 
-The priority queue is implemented as a binary heap of (key, priority value) pairs, which supports:
+``pqdict`` exposes an indexed priority queue as a mapping from keys to priority-determining values. The priority queue itself is implemented as a binary heap of (key, priority value) elements, which supports:
 
 * O(1) search for the item with highest priority
 
 * O(log n) removal of the item with highest priority
 
 * O(log n) insertion of a new item
 
-An internal index maps elements to their location in the heap and is kept up to date as the heap is manipulated. As a result, pqdict also supports:
+An internal index maps each key to its element's location in the heap and is kept up to date as the heap is manipulated. As a result, ``pqdict`` also supports:
 
 * O(1) lookup of any item by key
 
@@ -130,7 +130,7 @@ Views and regular iteration don't affect the heap, but the output is **unsorted*
     >>> pq.popitem()
     ('d', 6.5)
     >>> pq.popitem()  # ...and we're empty!
-    KeyError
+    Empty
 
 
 .. warning:: 
@@ -157,4 +157,4 @@ This module is released under the MIT license. The augmented heap implementation
 Documentation
 -------------
 
-Documentation is available at http://pqdict.readthedocs.org/en/latest/.
+Documentation is available at http://pqdict.readthedocs.org/.

pqdict/__init__.py

@@ -8,26 +8,27 @@
 Raymond Hettinger.
 
 The priority queue is implemented as a binary heap of (key, priority value)
-pairs, which supports:
+elements, which supports:
 
 - O(1) search for the item with highest priority
 
 - O(log n) removal of the item with highest priority
 
 - O(log n) insertion of a new item
 
-Additionally, an index maps elements to their location in the heap and is kept
-up to date as the heap is manipulated. As a result, pqdict also supports:
+Additionally, an index maps each key to its element's location in the heap
+and is kept up to date as the heap is manipulated. As a result, pqdict also
+supports:
 
 - O(1) lookup of any item by key
 
 - O(log n) removal of any item
 
 - O(log n) updating of any item's priority level
 
-Documentation at <http://pqdict.readthedocs.org/en/latest>.
+Documentation at <http://pqdict.readthedocs.org/>.
 
-:copyright: (c) 2012-2023 by Nezar Abdennur.
+:copyright: (c) 2012-2024 by Nezar Abdennur.
 :license: MIT, see LICENSE for more details.
 
 """
@@ -593,8 +594,8 @@ def popitems(self) -> Iterator[Tuple[Any, Any]]:
     def heapify(self, key: Any = __marker) -> None:
         """Repair a broken heap.
 
-        If the state of an item's priority value changes you can re-sort the
-        relevant item only by providing ``key``.
+        If a change in a single, mutable value caused the break, you can
+        provide ``key`` to repair the heap by relocating that item.
         """
         if key is self.__marker:
             heapify(self._heap, self._position, self._precedes)