functions for the common case where no key function is specified.

an alternate algorithm when the number of selected items is small
relative to the full iterable.

* Mark the C version as private and only use when available.

(From SF patch #810751)

empty heap, since heap[0] raises the appropriate IndexError already.

elements.

currently-smallest value, and add item, in one gulp.  See the second
N-Best algorithm in the test suite for a natural use.

substantially fewer array-element compares.  This is best practice as of
Kntuh Volume 3 Ed 2, and the code is actually simpler this way (although
the key idea may be counter-intuitive at first glance!  breaking out of
a loop early loses when it costs more to try to get out early than getting
out early saves).
Also added a comment block explaining the difference and giving some real
counts; demonstrating that heapify() is more efficient than repeated
heappush(); and emphasizing the obvious point thatlist.sort() is more
efficient if what you really want to do is sort.

in the test file.  I have docs for heapq.heapify ready to check in, but
Jack appears to have left behind a stale lock in the Doc/lib directory.

Added new heapify() function, which transforms an arbitrary list into a
heap in linear time; that's a fundamental tool for using heaps in real
life <wink>.

Added heapyify() test.  Added a "less naive" N-best algorithm to the test
suite, and noted that this could actually go much faster (building on
heapify()) if we had max-heaps instead of min-heaps (the iterative method
is appropriate when all the data isn't known in advance, but when it is
known in advance the tradeoffs get murkier).

a c-cedilla in one of the docstrings.

don't use division at all.

week.