Update: usage doc for heappushpop (GH-91451)
diff --git a/Lib/heapq.py b/Lib/heapq.py
index fabefd8..2fd9d1f 100644
--- a/Lib/heapq.py
+++ b/Lib/heapq.py
@@ -12,6 +12,8 @@
item = heappop(heap) # pops the smallest item from the heap
item = heap[0] # smallest item on the heap without popping it
heapify(x) # transforms list into a heap, in-place, in linear time
+item = heappushpop(heap, item) # pushes a new item and then returns
+ # the smallest item; the heap size is unchanged
item = heapreplace(heap, item) # pops and returns smallest item, and adds
# new item; the heap size is unchanged
