heapq docs should be more precise about how to access the smallest element

[elibendersky]

BPO	23549
Nosy	@rhettinger, @vadmium
Files	issue23549.1.patch issue23549.2.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2015-03-15.03:20:33.344>
created_at = <Date 2015-02-28.16:37:41.396>
labels = ['type-bug', 'docs']
title = 'heapq docs should be more precise about how to access the smallest element'
updated_at = <Date 2015-03-15.03:20:33.343>
user = 'https://bugs.python.org/elibendersky'

bugs.python.org fields:

activity = <Date 2015-03-15.03:20:33.343>
actor = 'eli.bendersky'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2015-03-15.03:20:33.344>
closer = 'eli.bendersky'
components = ['Documentation']
creation = <Date 2015-02-28.16:37:41.396>
creator = 'eli.bendersky'
dependencies = []
files = ['38277', '38280']
hgrepos = []
issue_num = 23549
keywords = ['patch']
message_count = 7.0
messages = ['236895', '236897', '236915', '236916', '237179', '238117', '238118']
nosy_count = 5.0
nosy_names = ['rhettinger', 'eli.bendersky', 'docs@python', 'python-dev', 'martin.panter']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue23549'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

[elibendersky]

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.

[elibendersky]

Proposed patch (generated vs. the 3.4 docs) is attached

[vadmium]

“Smalest” is spelt with a double L.

[elibendersky]

Good catch.

Attaching a new version of the patch with the typo fixed.

[elibendersky]

Raymond - gentle ping.

Do you see a reason not to check this in?

[python-dev]

New changeset 8ddda7d1f8e3 by Eli Bendersky in branch '3.4':
Issue bpo-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 bpo-23549: Clarify confusion in heapq doc - accessing the mininmal element
https://hg.python.org/cpython/rev/642247a536d5

[python-dev]

New changeset b61578bb5014 by Eli Bendersky in branch '2.7':
Issue bpo-23549: Clarify confusion in heapq doc - accessing the mininmal element
https://hg.python.org/cpython/rev/b61578bb5014