Improve the documented advice on how to best use heapq.heapreplace().

1 files changed, 3 insertions, 1 deletions

diff --git a/Lib/heapq.py b/Lib/heapq.py
index 09f996aff8..9fb4e70824 100644
--- a/Lib/heapq.py
+++ b/Lib/heapq.py
@@ -154,7 +154,9 @@ def heapreplace(heap, item):
     This is more efficient than heappop() followed by heappush(), and can be
     more appropriate when using a fixed-size heap.  Note that the value
     returned may be larger than item!  That constrains reasonable uses of
-    this routine.
+    this routine unless written as part of a larger expression:
+
+        result = item <= heap[0] and item  or  heapreplace(heap, item)
     """
     returnitem = heap[0]    # raises appropriate IndexError if heap is empty
     heap[0] = item