FM / python3.12

/snap/core24/1587/usr/lib/python3.12

Name	Size	Mode	Actions
asyncio/	-	0755	rm
collections/	-	0755	rm
concurrent/	-	0755	rm
ctypes/	-	0755	rm
curses/	-	0755	rm
dbm/	-	0755	rm
email/	-	0755	rm
encodings/	-	0755	rm
html/	-	0755	rm
http/	-	0755	rm
importlib/	-	0755	rm
json/	-	0755	rm
lib-dynload/	-	0755	rm
logging/	-	0755	rm
multiprocessing/	-	0755	rm
pydoc_data/	-	0755	rm
re/	-	0755	rm
sqlite3/	-	0755	rm
test/	-	0755	rm
tomllib/	-	0755	rm
unittest/	-	0755	rm
urllib/	-	0755	rm
venv/	-	0755	rm
wsgiref/	-	0755	rm
xml/	-	0755	rm
xmlrpc/	-	0755	rm
zipfile/	-	0755	rm
zoneinfo/	-	0755	rm
__phello__/	-	0755	rm
__pycache__/	-	0755	rm
abc.py	6538	0644	edit dl rm
aifc.py	34211	0644	edit dl rm
antigravity.py	500	0644	edit dl rm
argparse.py	101750	0644	edit dl rm
ast.py	64260	0644	edit dl rm
base64.py	20602	0755	edit dl rm
bdb.py	32463	0644	edit dl rm
bisect.py	3423	0644	edit dl rm
bz2.py	11847	0644	edit dl rm
calendar.py	25418	0644	edit dl rm
cgi.py	34418	0755	edit dl rm
cgitb.py	12421	0644	edit dl rm
chunk.py	5500	0644	edit dl rm
cmd.py	14873	0644	edit dl rm
code.py	10695	0644	edit dl rm
codecs.py	36870	0644	edit dl rm
codeop.py	5908	0644	edit dl rm
colorsys.py	4062	0644	edit dl rm
compileall.py	20598	0644	edit dl rm
configparser.py	53789	0644	edit dl rm
contextlib.py	27637	0644	edit dl rm
contextvars.py	129	0644	edit dl rm
copy.py	8412	0644	edit dl rm
copyreg.py	7614	0644	edit dl rm
cProfile.py	6555	0755	edit dl rm
crypt.py	3913	0644	edit dl rm
csv.py	16386	0644	edit dl rm
dataclasses.py	61753	0644	edit dl rm
datetime.py	268	0644	edit dl rm
decimal.py	320	0644	edit dl rm
difflib.py	83308	0644	edit dl rm
dis.py	30209	0644	edit dl rm
doctest.py	106479	0644	edit dl rm
enum.py	81636	0644	edit dl rm
EXTERNALLY-MANAGED	645	0644	edit dl rm
filecmp.py	10187	0644	edit dl rm
fileinput.py	15714	0644	edit dl rm
fnmatch.py	5999	0644	edit dl rm
fractions.py	38067	0644	edit dl rm
ftplib.py	34735	0644	edit dl rm
functools.py	38126	0644	edit dl rm
genericpath.py	5572	0644	edit dl rm
getopt.py	7488	0644	edit dl rm
getpass.py	5990	0644	edit dl rm
gettext.py	21747	0644	edit dl rm
glob.py	8732	0644	edit dl rm
graphlib.py	9656	0644	edit dl rm
gzip.py	24859	0644	edit dl rm
hashlib.py	9349	0644	edit dl rm
heapq.py	23024	0644	edit dl rm
hmac.py	7716	0644	edit dl rm
imaplib.py	53688	0644	edit dl rm
imghdr.py	4398	0644	edit dl rm
inspect.py	125420	0644	edit dl rm
io.py	3582	0644	edit dl rm
ipaddress.py	78294	0644	edit dl rm
keyword.py	1073	0644	edit dl rm
LICENSE.txt	13936	0644	edit dl rm
linecache.py	5649	0644	edit dl rm
locale.py	78562	0644	edit dl rm
lzma.py	13277	0644	edit dl rm
mailbox.py	78911	0644	edit dl rm
mailcap.py	9333	0644	edit dl rm
mimetypes.py	22888	0644	edit dl rm
modulefinder.py	23699	0644	edit dl rm
netrc.py	6922	0644	edit dl rm
nntplib.py	41087	0644	edit dl rm
ntpath.py	30027	0644	edit dl rm
nturl2path.py	2887	0644	edit dl rm
numbers.py	11467	0644	edit dl rm
opcode.py	13174	0644	edit dl rm
operator.py	10965	0644	edit dl rm
optparse.py	60369	0644	edit dl rm
os.py	39786	0644	edit dl rm
pathlib.py	51153	0644	edit dl rm
pdb.py	69459	0755	edit dl rm
pickle.py	64901	0644	edit dl rm
pickletools.py	93861	0644	edit dl rm
pipes.py	8978	0644	edit dl rm
pkgutil.py	18281	0644	edit dl rm
platform.py	43331	0755	edit dl rm
plistlib.py	28582	0644	edit dl rm
poplib.py	14163	0644	edit dl rm
posixpath.py	17623	0644	edit dl rm
pprint.py	24158	0644	edit dl rm
profile.py	23092	0755	edit dl rm
pstats.py	29289	0644	edit dl rm
pty.py	6137	0644	edit dl rm
pyclbr.py	11396	0644	edit dl rm
pydoc.py	113090	0755	edit dl rm
py_compile.py	7878	0644	edit dl rm
queue.py	11496	0644	edit dl rm
quopri.py	7183	0755	edit dl rm
random.py	34683	0644	edit dl rm
reprlib.py	6569	0644	edit dl rm
rlcompleter.py	7827	0644	edit dl rm
runpy.py	12898	0644	edit dl rm
sched.py	6351	0644	edit dl rm
secrets.py	1984	0644	edit dl rm
selectors.py	19671	0644	edit dl rm
shelve.py	8560	0644	edit dl rm
shlex.py	13353	0644	edit dl rm
shutil.py	58120	0644	edit dl rm
signal.py	2495	0644	edit dl rm
site.py	23903	0644	edit dl rm
sitecustomize.py	-	0	edit dl rm
smtplib.py	43531	0755	edit dl rm
sndhdr.py	7448	0644	edit dl rm
socket.py	37411	0644	edit dl rm
socketserver.py	27851	0644	edit dl rm
sre_compile.py	231	0644	edit dl rm
sre_constants.py	232	0644	edit dl rm
sre_parse.py	229	0644	edit dl rm
ssl.py	50822	0644	edit dl rm
stat.py	5485	0644	edit dl rm
statistics.py	50227	0644	edit dl rm
string.py	11786	0644	edit dl rm
stringprep.py	12917	0644	edit dl rm
struct.py	257	0644	edit dl rm
subprocess.py	88725	0644	edit dl rm
sunau.py	18478	0644	edit dl rm
symtable.py	10753	0644	edit dl rm
sysconfig.py	32768	0644	edit dl rm
tabnanny.py	11530	0755	edit dl rm
tarfile.py	112555	0755	edit dl rm
telnetlib.py	23301	0644	edit dl rm
tempfile.py	37334	0644	edit dl rm
textwrap.py	19718	0644	edit dl rm
this.py	1003	0644	edit dl rm
threading.py	60123	0644	edit dl rm
timeit.py	13463	0755	edit dl rm
token.py	2479	0644	edit dl rm
tokenize.py	21214	0644	edit dl rm
trace.py	29182	0755	edit dl rm
traceback.py	46325	0644	edit dl rm
tracemalloc.py	18047	0644	edit dl rm
tty.py	2035	0644	edit dl rm
turtle.py	146361	0644	edit dl rm
types.py	10993	0644	edit dl rm
typing.py	117428	0644	edit dl rm
uu.py	7364	0755	edit dl rm
uuid.py	29656	0644	edit dl rm
warnings.py	21760	0644	edit dl rm
wave.py	22769	0644	edit dl rm
weakref.py	21513	0644	edit dl rm
webbrowser.py	23627	0755	edit dl rm
xdrlib.py	5942	0644	edit dl rm
zipapp.py	7543	0644	edit dl rm
zipimport.py	28132	0644	edit dl rm
_aix_support.py	4021	0644	edit dl rm
_collections_abc.py	32082	0644	edit dl rm
_compat_pickle.py	8761	0644	edit dl rm
_compression.py	5681	0644	edit dl rm
_distutils_system_mod.py	5716	0644	edit dl rm
_markupbase.py	14653	0644	edit dl rm
_osx_support.py	22023	0644	edit dl rm
_pydatetime.py	92097	0644	edit dl rm
_pydecimal.py	229220	0644	edit dl rm
_pyio.py	93593	0644	edit dl rm
_pylong.py	9047	0644	edit dl rm
_py_abc.py	6189	0644	edit dl rm
_sitebuiltins.py	3128	0644	edit dl rm
_strptime.py	24615	0644	edit dl rm
_sysconfigdata__linux_x86_64-linux-gnu.py	49505	0644	edit dl rm
_sysconfigdata__x86_64-linux-gnu.py	49505	0644	edit dl rm
_threading_local.py	7220	0644	edit dl rm
_weakrefset.py	5893	0644	edit dl rm
__future__.py	5218	0644	edit dl rm
__hello__.py	227	0644	edit dl rm

Edit: /snap/core24/1587/usr/lib/python3.12/heapq.py (23024B)

"""Heap queue algorithm (a.k.a. priority queue).

Heaps are arrays for which a[k] <= a[2*k+1] and a[k] <= a[2*k+2] for
all k, counting elements from 0.  For the sake of comparison,
non-existing elements are considered to be infinite.  The interesting
property of a heap is that a[0] is always its smallest element.

Usage:

heap = []            # creates an empty heap
heappush(heap, item) # pushes a new item on the heap
item = heappop(heap) # pops the smallest item from the heap
item = heap[0]       # smallest item on the heap without popping it
heapify(x)           # transforms list into a heap, in-place, in linear time
item = heappushpop(heap, item) # pushes a new item and then returns
                               # the smallest item; the heap size is unchanged
item = heapreplace(heap, item) # pops and returns smallest item, and adds
                               # new item; the heap size is unchanged

Our API differs from textbook heap algorithms as follows:

- We use 0-based indexing.  This makes the relationship between the
  index for a node and the indexes for its children slightly less
  obvious, but is more suitable since Python uses 0-based indexing.

- Our heappop() method returns the smallest item, not the largest.

These two make it possible to view the heap as a regular Python list
without surprises: heap[0] is the smallest item, and heap.sort()
maintains the heap invariant!
"""

# Original code by Kevin O'Connor, augmented by Tim Peters and Raymond Hettinger

__about__ = """Heap queues

[explanation by François Pinard]

The strange invariant above is meant to be an efficient memory
representation for a tournament.  The numbers below are `k', not a[k]:

1                                 2

3               4                5               6

7       8       9       10      11      12      13      14

15 16   17 18   19 20   21 22   23 24   25 26   27 28   29 30

In the tree above, each cell `k' is topping `2*k+1' and `2*k+2'.  In
a usual binary tournament we see in sports, each cell is the winner
over the two cells it tops, and we can trace the winner down the tree
to see all opponents s/he had.  However, in many computer applications
of such tournaments, we do not need to trace the history of a winner.
To be more memory efficient, when a winner is promoted, we try to
replace it by something else at a lower level, and the rule becomes
that a cell and the two cells it tops contain three different items,
but the top cell "wins" over the two topped cells.

If this heap invariant is protected at all time, index 0 is clearly
the overall winner.  The simplest algorithmic way to remove it and
find the "next" winner is to move some loser (let's say cell 30 in the
diagram above) into the 0 position, and then percolate this new 0 down
the tree, exchanging values, until the invariant is re-established.
This is clearly logarithmic on the total number of items in the tree.
By iterating over all items, you get an O(n ln n) sort.

A nice feature of this sort is that you can efficiently insert new
items while the sort is going on, provided that the inserted items are
not "better" than the last 0'th element you extracted.  This is
especially useful in simulation contexts, where the tree holds all
incoming events, and the "win" condition means the smallest scheduled
time.  When an event schedule other events for execution, they are
scheduled into the future, so they can easily go into the heap.  So, a
heap is a good structure for implementing schedulers (this is what I
used for my MIDI sequencer :-).

Various structures for implementing schedulers have been extensively
studied, and heaps are good for this, as they are reasonably speedy,
the speed is almost constant, and the worst case is not much different
than the average case.  However, there are other representations which
are more efficient overall, yet the worst cases might be terrible.

Heaps are also very useful in big disk sorts.  You most probably all
know that a big sort implies producing "runs" (which are pre-sorted
sequences, which size is usually related to the amount of CPU memory),
followed by a merging passes for these runs, which merging is often
very cleverly organised[1].  It is very important that the initial
sort produces the longest runs possible.  Tournaments are a good way
to that.  If, using all the memory available to hold a tournament, you
replace and percolate items that happen to fit the current run, you'll
produce runs which are twice the size of the memory for random input,
and much better for input fuzzily ordered.

Moreover, if you output the 0'th item on disk and get an input which
may not fit in the current tournament (because the value "wins" over
the last output value), it cannot fit in the heap, so the size of the
heap decreases.  The freed memory could be cleverly reused immediately
for progressively building a second heap, which grows at exactly the
same rate the first heap is melting.  When the first heap completely
vanishes, you switch heaps and start a new run.  Clever and quite
effective!

In a word, heaps are useful memory structures to know.  I use them in
a few applications, and I think it is good to keep a `heap' module
around. :-)

--------------------
[1] The disk balancing algorithms which are current, nowadays, are
more annoying than clever, and this is a consequence of the seeking
capabilities of the disks.  On devices which cannot seek, like big
tape drives, the story was quite different, and one had to be very
clever to ensure (far in advance) that each tape movement will be the
most effective possible (that is, will best participate at
"progressing" the merge).  Some tapes were even able to read
backwards, and this was also used to avoid the rewinding time.
Believe me, real good tape sorts were quite spectacular to watch!
From all times, sorting has always been a Great Art! :-)
"""

__all__ = ['heappush', 'heappop', 'heapify', 'heapreplace', 'merge',
           'nlargest', 'nsmallest', 'heappushpop']

def heappush(heap, item):
    """Push item onto heap, maintaining the heap invariant."""
    heap.append(item)
    _siftdown(heap, 0, len(heap)-1)

def heappop(heap):
    """Pop the smallest item off the heap, maintaining the heap invariant."""
    lastelt = heap.pop()    # raises appropriate IndexError if heap is empty
    if heap:
        returnitem = heap[0]
        heap[0] = lastelt
        _siftup(heap, 0)
        return returnitem
    return lastelt

def heapreplace(heap, item):
    """Pop and return the current smallest value, and add the new item.

This is more efficient than heappop() followed by heappush(), and can be
    more appropriate when using a fixed-size heap.  Note that the value
    returned may be larger than item!  That constrains reasonable uses of
    this routine unless written as part of a conditional replacement:

if item > heap[0]:
            item = heapreplace(heap, item)
    """
    returnitem = heap[0]    # raises appropriate IndexError if heap is empty
    heap[0] = item
    _siftup(heap, 0)
    return returnitem

def heappushpop(heap, item):
    """Fast version of a heappush followed by a heappop."""
    if heap and heap[0] < item:
        item, heap[0] = heap[0], item
        _siftup(heap, 0)
    return item

def heapify(x):
    """Transform list into a heap, in-place, in O(len(x)) time."""
    n = len(x)
    # Transform bottom-up.  The largest index there's any point to looking at
    # is the largest with a child index in-range, so must have 2*i + 1 < n,
    # or i < (n-1)/2.  If n is even = 2*j, this is (2*j-1)/2 = j-1/2 so
    # j-1 is the largest, which is n//2 - 1.  If n is odd = 2*j+1, this is
    # (2*j+1-1)/2 = j so j-1 is the largest, and that's again n//2-1.
    for i in reversed(range(n//2)):
        _siftup(x, i)

def _heappop_max(heap):
    """Maxheap version of a heappop."""
    lastelt = heap.pop()    # raises appropriate IndexError if heap is empty
    if heap:
        returnitem = heap[0]
        heap[0] = lastelt
        _siftup_max(heap, 0)
        return returnitem
    return lastelt

def _heapreplace_max(heap, item):
    """Maxheap version of a heappop followed by a heappush."""
    returnitem = heap[0]    # raises appropriate IndexError if heap is empty
    heap[0] = item
    _siftup_max(heap, 0)
    return returnitem

def _heapify_max(x):
    """Transform list into a maxheap, in-place, in O(len(x)) time."""
    n = len(x)
    for i in reversed(range(n//2)):
        _siftup_max(x, i)

# 'heap' is a heap at all indices >= startpos, except possibly for pos.  pos
# is the index of a leaf with a possibly out-of-order value.  Restore the
# heap invariant.
def _siftdown(heap, startpos, pos):
    newitem = heap[pos]
    # Follow the path to the root, moving parents down until finding a place
    # newitem fits.
    while pos > startpos:
        parentpos = (pos - 1) >> 1
        parent = heap[parentpos]
        if newitem < parent:
            heap[pos] = parent
            pos = parentpos
            continue
        break
    heap[pos] = newitem

# The child indices of heap index pos are already heaps, and we want to make
# a heap at index pos too.  We do this by bubbling the smaller child of
# pos up (and so on with that child's children, etc) until hitting a leaf,
# then using _siftdown to move the oddball originally at index pos into place.
#
# We *could* break out of the loop as soon as we find a pos where newitem <=
# both its children, but turns out that's not a good idea, and despite that
# many books write the algorithm that way.  During a heap pop, the last array
# element is sifted in, and that tends to be large, so that comparing it
# against values starting from the root usually doesn't pay (= usually doesn't
# get us out of the loop early).  See Knuth, Volume 3, where this is
# explained and quantified in an exercise.
#
# Cutting the # of comparisons is important, since these routines have no
# way to extract "the priority" from an array element, so that intelligence
# is likely to be hiding in custom comparison methods, or in array elements
# storing (priority, record) tuples.  Comparisons are thus potentially
# expensive.
#
# On random arrays of length 1000, making this change cut the number of
# comparisons made by heapify() a little, and those made by exhaustive
# heappop() a lot, in accord with theory.  Here are typical results from 3
# runs (3 just to demonstrate how small the variance is):
#
# Compares needed by heapify     Compares needed by 1000 heappops
# --------------------------     --------------------------------
# 1837 cut to 1663               14996 cut to 8680
# 1855 cut to 1659               14966 cut to 8678
# 1847 cut to 1660               15024 cut to 8703
#
# Building the heap by using heappush() 1000 times instead required
# 2198, 2148, and 2219 compares:  heapify() is more efficient, when
# you can use it.
#
# The total compares needed by list.sort() on the same lists were 8627,
# 8627, and 8632 (this should be compared to the sum of heapify() and
# heappop() compares):  list.sort() is (unsurprisingly!) more efficient
# for sorting.

def _siftup(heap, pos):
    endpos = len(heap)
    startpos = pos
    newitem = heap[pos]
    # Bubble up the smaller child until hitting a leaf.
    childpos = 2*pos + 1    # leftmost child position
    while childpos < endpos:
        # Set childpos to index of smaller child.
        rightpos = childpos + 1
        if rightpos < endpos and not heap[childpos] < heap[rightpos]:
            childpos = rightpos
        # Move the smaller child up.
        heap[pos] = heap[childpos]
        pos = childpos
        childpos = 2*pos + 1
    # The leaf at pos is empty now.  Put newitem there, and bubble it up
    # to its final resting place (by sifting its parents down).
    heap[pos] = newitem
    _siftdown(heap, startpos, pos)

def _siftdown_max(heap, startpos, pos):
    'Maxheap variant of _siftdown'
    newitem = heap[pos]
    # Follow the path to the root, moving parents down until finding a place
    # newitem fits.
    while pos > startpos:
        parentpos = (pos - 1) >> 1
        parent = heap[parentpos]
        if parent < newitem:
            heap[pos] = parent
            pos = parentpos
            continue
        break
    heap[pos] = newitem

def _siftup_max(heap, pos):
    'Maxheap variant of _siftup'
    endpos = len(heap)
    startpos = pos
    newitem = heap[pos]
    # Bubble up the larger child until hitting a leaf.
    childpos = 2*pos + 1    # leftmost child position
    while childpos < endpos:
        # Set childpos to index of larger child.
        rightpos = childpos + 1
        if rightpos < endpos and not heap[rightpos] < heap[childpos]:
            childpos = rightpos
        # Move the larger child up.
        heap[pos] = heap[childpos]
        pos = childpos
        childpos = 2*pos + 1
    # The leaf at pos is empty now.  Put newitem there, and bubble it up
    # to its final resting place (by sifting its parents down).
    heap[pos] = newitem
    _siftdown_max(heap, startpos, pos)

def merge(*iterables, key=None, reverse=False):
    '''Merge multiple sorted inputs into a single sorted output.

Similar to sorted(itertools.chain(*iterables)) but returns a generator,
    does not pull the data into memory all at once, and assumes that each of
    the input streams is already sorted (smallest to largest).

>>> list(merge([1,3,5,7], [0,2,4,8], [5,10,15,20], [], [25]))
    [0, 1, 2, 3, 4, 5, 5, 7, 8, 10, 15, 20, 25]

If *key* is not None, applies a key function to each element to determine
    its sort order.

>>> list(merge(['dog', 'horse'], ['cat', 'fish', 'kangaroo'], key=len))
    ['dog', 'cat', 'fish', 'horse', 'kangaroo']

'''

h = []
    h_append = h.append

if reverse:
        _heapify = _heapify_max
        _heappop = _heappop_max
        _heapreplace = _heapreplace_max
        direction = -1
    else:
        _heapify = heapify
        _heappop = heappop
        _heapreplace = heapreplace
        direction = 1

if key is None:
        for order, it in enumerate(map(iter, iterables)):
            try:
                next = it.__next__
                h_append([next(), order * direction, next])
            except StopIteration:
                pass
        _heapify(h)
        while len(h) > 1:
            try:
                while True:
                    value, order, next = s = h[0]
                    yield value
                    s[0] = next()           # raises StopIteration when exhausted
                    _heapreplace(h, s)      # restore heap condition
            except StopIteration:
                _heappop(h)                 # remove empty iterator
        if h:
            # fast case when only a single iterator remains
            value, order, next = h[0]
            yield value
            yield from next.__self__
        return

for order, it in enumerate(map(iter, iterables)):
        try:
            next = it.__next__
            value = next()
            h_append([key(value), order * direction, value, next])
        except StopIteration:
            pass
    _heapify(h)
    while len(h) > 1:
        try:
            while True:
                key_value, order, value, next = s = h[0]
                yield value
                value = next()
                s[0] = key(value)
                s[2] = value
                _heapreplace(h, s)
        except StopIteration:
            _heappop(h)
    if h:
        key_value, order, value, next = h[0]
        yield value
        yield from next.__self__

# Algorithm notes for nlargest() and nsmallest()
# ==============================================
#
# Make a single pass over the data while keeping the k most extreme values
# in a heap.  Memory consumption is limited to keeping k values in a list.
#
# Measured performance for random inputs:
#
#                                   number of comparisons
#    n inputs     k-extreme values  (average of 5 trials)   % more than min()
# -------------   ----------------  ---------------------   -----------------
#      1,000           100                  3,317               231.7%
#     10,000           100                 14,046                40.5%
#    100,000           100                105,749                 5.7%
#  1,000,000           100              1,007,751                 0.8%
# 10,000,000           100             10,009,401                 0.1%
#
# Theoretical number of comparisons for k smallest of n random inputs:
#
# Step   Comparisons                  Action
# ----   --------------------------   ---------------------------
#  1     1.66 * k                     heapify the first k-inputs
#  2     n - k                        compare remaining elements to top of heap
#  3     k * (1 + lg2(k)) * ln(n/k)   replace the topmost value on the heap
#  4     k * lg2(k) - (k/2)           final sort of the k most extreme values
#
# Combining and simplifying for a rough estimate gives:
#
#        comparisons = n + k * (log(k, 2) * log(n/k) + log(k, 2) + log(n/k))
#
# Computing the number of comparisons for step 3:
# -----------------------------------------------
# * For the i-th new value from the iterable, the probability of being in the
#   k most extreme values is k/i.  For example, the probability of the 101st
#   value seen being in the 100 most extreme values is 100/101.
# * If the value is a new extreme value, the cost of inserting it into the
#   heap is 1 + log(k, 2).
# * The probability times the cost gives:
#            (k/i) * (1 + log(k, 2))
# * Summing across the remaining n-k elements gives:
#            sum((k/i) * (1 + log(k, 2)) for i in range(k+1, n+1))
# * This reduces to:
#            (H(n) - H(k)) * k * (1 + log(k, 2))
# * Where H(n) is the n-th harmonic number estimated by:
#            gamma = 0.5772156649
#            H(n) = log(n, e) + gamma + 1 / (2 * n)
#   http://en.wikipedia.org/wiki/Harmonic_series_(mathematics)#Rate_of_divergence
# * Substituting the H(n) formula:
#            comparisons = k * (1 + log(k, 2)) * (log(n/k, e) + (1/n - 1/k) / 2)
#
# Worst-case for step 3:
# ----------------------
# In the worst case, the input data is reversed sorted so that every new element
# must be inserted in the heap:
#
#             comparisons = 1.66 * k + log(k, 2) * (n - k)
#
# Alternative Algorithms
# ----------------------
# Other algorithms were not used because they:
# 1) Took much more auxiliary memory,
# 2) Made multiple passes over the data.
# 3) Made more comparisons in common cases (small k, large n, semi-random input).
# See the more detailed comparison of approach at:
# http://code.activestate.com/recipes/577573-compare-algorithms-for-heapqsmallest

def nsmallest(n, iterable, key=None):
    """Find the n smallest elements in a dataset.

Equivalent to:  sorted(iterable, key=key)[:n]
    """

# Short-cut for n==1 is to use min()
    if n == 1:
        it = iter(iterable)
        sentinel = object()
        result = min(it, default=sentinel, key=key)
        return [] if result is sentinel else [result]

# When n>=size, it's faster to use sorted()
    try:
        size = len(iterable)
    except (TypeError, AttributeError):
        pass
    else:
        if n >= size:
            return sorted(iterable, key=key)[:n]

# When key is none, use simpler decoration
    if key is None:
        it = iter(iterable)
        # put the range(n) first so that zip() doesn't
        # consume one too many elements from the iterator
        result = [(elem, i) for i, elem in zip(range(n), it)]
        if not result:
            return result
        _heapify_max(result)
        top = result[0][0]
        order = n
        _heapreplace = _heapreplace_max
        for elem in it:
            if elem < top:
                _heapreplace(result, (elem, order))
                top, _order = result[0]
                order += 1
        result.sort()
        return [elem for (elem, order) in result]

# General case, slowest method
    it = iter(iterable)
    result = [(key(elem), i, elem) for i, elem in zip(range(n), it)]
    if not result:
        return result
    _heapify_max(result)
    top = result[0][0]
    order = n
    _heapreplace = _heapreplace_max
    for elem in it:
        k = key(elem)
        if k < top:
            _heapreplace(result, (k, order, elem))
            top, _order, _elem = result[0]
            order += 1
    result.sort()
    return [elem for (k, order, elem) in result]

def nlargest(n, iterable, key=None):
    """Find the n largest elements in a dataset.

Equivalent to:  sorted(iterable, key=key, reverse=True)[:n]
    """

# Short-cut for n==1 is to use max()
    if n == 1:
        it = iter(iterable)
        sentinel = object()
        result = max(it, default=sentinel, key=key)
        return [] if result is sentinel else [result]

# When n>=size, it's faster to use sorted()
    try:
        size = len(iterable)
    except (TypeError, AttributeError):
        pass
    else:
        if n >= size:
            return sorted(iterable, key=key, reverse=True)[:n]

# When key is none, use simpler decoration
    if key is None:
        it = iter(iterable)
        result = [(elem, i) for i, elem in zip(range(0, -n, -1), it)]
        if not result:
            return result
        heapify(result)
        top = result[0][0]
        order = -n
        _heapreplace = heapreplace
        for elem in it:
            if top < elem:
                _heapreplace(result, (elem, order))
                top, _order = result[0]
                order -= 1
        result.sort(reverse=True)
        return [elem for (elem, order) in result]

# General case, slowest method
    it = iter(iterable)
    result = [(key(elem), i, elem) for i, elem in zip(range(0, -n, -1), it)]
    if not result:
        return result
    heapify(result)
    top = result[0][0]
    order = -n
    _heapreplace = heapreplace
    for elem in it:
        k = key(elem)
        if top < k:
            _heapreplace(result, (k, order, elem))
            top, _order, _elem = result[0]
            order -= 1
    result.sort(reverse=True)
    return [elem for (k, order, elem) in result]

# If available, use C implementation
try:
    from _heapq import *
except ImportError:
    pass
try:
    from _heapq import _heapreplace_max
except ImportError:
    pass
try:
    from _heapq import _heapify_max
except ImportError:
    pass
try:
    from _heapq import _heappop_max
except ImportError:
    pass

if __name__ == "__main__":

import doctest # pragma: no cover
    print(doctest.testmod()) # pragma: no cover

cmd: