>>> import heapq
>>> help(heapq)
Help on module heapq:

NAME
    heapq - Heap queue algorithm (a.k.a. priority queue).

FILE
    c:\python27\lib\heapq.py

DESCRIPTION
    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 = 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!

FUNCTIONS
    heapify(...)
        Transform list into a heap, in-place, in O(len(heap)) time.
    
    heappop(...)
        Pop the smallest item off the heap, maintaining the heap invariant.
    
    heappush(...)
        heappush(heap, item) -> None. Push item onto heap, maintaining the heap invariant.
    
    heappushpop(...)
        heappushpop(heap, item) -> value. Push item on the heap, then pop and return the smallest item
        from the heap. The combined action runs more efficiently than
        heappush() followed by a separate call to heappop().
    
    heapreplace(...)
        heapreplace(heap, item) -> value. 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)
    
    merge(*iterables)
        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]
    
    nlargest(n, iterable, key=None)
        Find the n largest elements in a dataset.
        
        Equivalent to:  sorted(iterable, key=key, reverse=True)[:n]
    
    nsmallest(n, iterable, key=None)
        Find the n smallest elements in a dataset.
        
        Equivalent to:  sorted(iterable, key=key)[:n]

DATA
    __about__ = 'Heap queues\n\n[explanation by Fran\xe7ois Pinard]\n\nH.....
    __all__ = ['heappush', 'heappop', 'heapify', 'heapreplace', 'merge', '...
 

demo：

>>> a_list = [1,4,5,2,6,9,0,3]
#把list轉化成heap
>>> heapq.heapify(a_list)   
>>> a_list
[0, 2, 1, 3, 6, 9, 5, 4]
#選出n個最大和最小值。 O(n)時間複雜度
>>> heapq.nlargest(3,a_list)
[9, 6, 5]
>>> heapq.nsmallest(3,a_list)
[0, 1, 2]

>>> heapq.heappushpop(a_list,7)
0
#返回當前最小值，再新增新元素
>>> heapq.heapreplace(a_list,-1)
1
>>> a_list
[-1, 2, 5, 3, 6, 9, 7, 4]
#新增新元素並返回最小值
>>> heapq.heappushpop(a_list,-2)
-2
>>> a_list
[-1, 2, 5, 3, 6, 9, 7, 4]