classification
Title: heapq docs should be more precise about how to access the smallest element
Type: behavior Stage:
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, eli.bendersky, martin.panter, python-dev, rhettinger
Priority: normal Keywords: patch

Created on 2015-02-28 16:37 by eli.bendersky, last changed 2015-03-15 03:20 by eli.bendersky. This issue is now closed.

Files
File name Uploaded Description Edit
issue23549.1.patch eli.bendersky, 2015-02-28 16:47
issue23549.2.patch eli.bendersky, 2015-02-28 21:48
Messages (7)
msg236895 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2015-02-28 16:37
The heapq documentation has this paragraph after the doc of nsmallest:

  The latter two functions perform best for smaller values of n. For larger values, it is more efficient to use the sorted() function. Also, when n==1, it is more efficient to use the built-in min() and max() functions.

This is confusing as it suggests to use min() on a heap to find the minimal element.

heap[0] is the minimal element, but this is only mentioned at the very top - so you need to read the doc of the entire module to find it. Nothing in the docs of methods suggests it.
msg236897 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2015-02-28 16:47
Proposed patch (generated vs. the 3.4 docs) is attached
msg236915 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-02-28 21:46
“Smalest” is spelt with a double L.
msg236916 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2015-02-28 21:48
Good catch.

Attaching a new version of the patch with the typo fixed.
msg237179 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2015-03-04 14:35
Raymond - gentle ping.

Do you see a reason not to check this in?
msg238117 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-03-15 03:17
New changeset 8ddda7d1f8e3 by Eli Bendersky in branch '3.4':
Issue #23549: Clarify confusion in heapq doc - accessing the mininmal element
https://hg.python.org/cpython/rev/8ddda7d1f8e3

New changeset 642247a536d5 by Eli Bendersky in branch 'default':
Issue #23549: Clarify confusion in heapq doc - accessing the mininmal element
https://hg.python.org/cpython/rev/642247a536d5
msg238118 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-03-15 03:20
New changeset b61578bb5014 by Eli Bendersky in branch '2.7':
Issue #23549: Clarify confusion in heapq doc - accessing the mininmal element
https://hg.python.org/cpython/rev/b61578bb5014
History
Date User Action Args
2015-03-15 03:20:33eli.benderskysetstatus: open -> closed
resolution: fixed
2015-03-15 03:20:17python-devsetmessages: + msg238118
2015-03-15 03:17:21python-devsetnosy: + python-dev
messages: + msg238117
2015-03-04 14:35:07eli.benderskysetmessages: + msg237179
2015-02-28 21:48:40eli.benderskysetfiles: + issue23549.2.patch

messages: + msg236916
2015-02-28 21:46:58martin.pantersetnosy: + martin.panter
messages: + msg236915
2015-02-28 20:16:57rhettingersetassignee: docs@python -> rhettinger

nosy: + rhettinger
2015-02-28 16:47:23eli.benderskysetfiles: + issue23549.1.patch
keywords: + patch
messages: + msg236897
2015-02-28 16:37:41eli.benderskycreate