[Python-checkins] cpython (2.7): Issue #23549: Clarify confusion in heapq doc - accessing the mininmal element

[eli.bendersky]

https://hg.python.org/cpython/rev/b61578bb5014
changeset:   94998:b61578bb5014
branch:      2.7
parent:      94990:b617790557b3
user:        Eli Bendersky <eliben at gmail.com>
date:        Sat Mar 14 20:20:36 2015 -0700
summary:
  Issue #23549: Clarify confusion in heapq doc - accessing the mininmal element

The current documentation only mentions heap[0] as the smallest element in the
beginning, and not in any of the methods' docs. There's no method to access the
minimal element without popping it, and the documentation of nsmallest is
confusing because it may suggest that min() is the way to go for n==1.
default

files:
  Doc/library/heapq.rst |  6 ++++--
  1 files changed, 4 insertions(+), 2 deletions(-)


diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst
--- a/Doc/library/heapq.rst
+++ b/Doc/library/heapq.rst
@@ -49,7 +49,8 @@
 .. function:: heappop(heap)
 
    Pop and return the smallest item from the *heap*, maintaining the heap
-   invariant.  If the heap is empty, :exc:`IndexError` is raised.
+   invariant.  If the heap is empty, :exc:`IndexError` is raised.  To access the
+   smallest item without popping it, use ``heap[0]``.
 
 .. function:: heappushpop(heap, item)
 
@@ -125,7 +126,8 @@
 The latter two functions perform best for smaller values of *n*.  For larger
 values, it is more efficient to use the :func:`sorted` function.  Also, when
 ``n==1``, it is more efficient to use the built-in :func:`min` and :func:`max`
-functions.
+functions.  If repeated usage of these functions is required, consider turning
+the iterable into an actual heap.
 
 
 Basic Examples

-- 
Repository URL: https://hg.python.org/cpython