[issue32142] heapq.heappop - documentation misleading or doesn't work

Change by Cheryl Sabella : -- resolution: -> rejected stage: -> resolved status: open -> closed ___ Python tracker ___ ___

[issue32142] heapq.heappop - documentation misleading or doesn't work

Raymond Hettinger added the comment: We could apply David Murray's suggested wording but I don't think it would actually help anyone. There are worked out examples from basic to advanced and a detailed section on the theory as well. ISTM, that prior to reading the docs, the OP likely

[issue32142] heapq.heappop - documentation misleading or doesn't work

R. David Murray added the comment: I would suggested following the statement "To create a heap, use a list initialized to [], or you can transform a populated list into a heap via function heapify()." with "Any mutation of the list thereafter must maintain the heap

[issue32142] heapq.heappop - documentation misleading or doesn't work

Change by Raymond Hettinger : -- assignee: docs@python -> rhettinger nosy: +rhettinger ___ Python tracker ___

[issue32142] heapq.heappop - documentation misleading or doesn't work

Scott Queen added the comment: Fair statement. "Properly sorted" was a poor choice. Seems that "if the invariant is true as a precondition, it will be true as a postcondition" is accurate and descriptive - maybe with a caution that modifying the list (heap) values by means

[issue32142] heapq.heappop - documentation misleading or doesn't work

Eric V. Smith added the comment: By "sorted" I meant "sorted by the heap functions so as to maintain their invariants". I don't have any suggestion for the actual specific language to use. -- ___ Python tracker

[issue32142] heapq.heappop - documentation misleading or doesn't work

abcdef added the comment: > Perhaps heappop could say that the heap invariant is maintained if the heap > is properly sorted before the heappop invocation. Honestly I like this wording less. "Properly sorted" would suggest sorted in the sense of heap.sort() [as the docs

[issue32142] heapq.heappop - documentation misleading or doesn't work

Eric V. Smith added the comment: The heap invariant is also required in order to even meet the documented behavior of returning the smallest item. >>> import heapq >>> li = [5, 7, 9, 1, 4, 3] >>> heapq.heapify(li) >>> li [1, 4, 3, 7, 5, 9] >>> li[2] = 0 >>>

[issue32142] heapq.heappop - documentation misleading or doesn't work

New submission from Scott Queen : The documentation for heapq.heappop(heap) says: "Pop and return the smallest item from the heap, maintaining the heap invariant. If the heap is empty, IndexError is raised. To access the smallest item without popping it, use heap[0]."