bpo-31145: Use dataclasses to create a prioritization wrapper (#5153)

2 files changed, 21 insertions, 0 deletions

diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst
index e36ca8d..0b1a3c8 100644
--- a/Doc/library/heapq.rst
+++ b/Doc/library/heapq.rst
@@ -187,6 +187,17 @@ a tie-breaker so that two tasks with the same priority are returned in the order
 they were added. And since no two entry counts are the same, the tuple
 comparison will never attempt to directly compare two tasks.
 
+Another solution to the problem of non-comparable tasks is to create a wrapper
+class that ignores the task item and only compares the priority field::
+
+    from dataclasses import dataclass, field
+    from typing import Any
+
+    @dataclass(order=True)
+    class PrioritizedItem:
+        priority: int
+        item: Any=field(compare=False)
+
 The remaining challenges revolve around finding a pending task and making
 changes to its priority or removing it entirely.  Finding a task can be done
 with a dictionary pointing to an entry in the queue.
diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst
index bd0fc2d..f9a43bb 100644
--- a/Doc/library/queue.rst
+++ b/Doc/library/queue.rst
@@ -56,6 +56,16 @@ The :mod:`queue` module defines the following classes and exceptions:
    one returned by ``sorted(list(entries))[0]``).  A typical pattern for entries
    is a tuple in the form: ``(priority_number, data)``.
 
+   If the *data* elements are not comparable, the data can be wrapped in a class
+   that ignores the data item and only compares the priority number::
+
+        from dataclasses import dataclass, field
+        from typing import Any
+
+        @dataclass(order=True)
+        class PrioritizedItem:
+            priority: int
+            item: Any=field(compare=False)
 
 .. exception:: Empty