pqdict 0.3 (beta)

An indexed priority queue implementation with a dictionary interface

What is an "indexed" priority queue?

A priority queue is an abstract data structure that allows you to serve elements in a prioritized fashion. You can insert elements with priorities, and remove or peek at the top priority element. Unlike a standard priority queue, an indexed priority queue additionally allows you to alter the priority of any element in the queue. With the right implementation, each of these operations can be done quite efficiently.

How does it work?

The priority queue is implemented as a binary heap (using a python list), which supports:

• O(1) access to the top priority element
• O(log n) removal of the top priority element
• O(log n) insertion of a new element

In addition, an internal dictionary or "index" maps elements to their position in the heap. This index is synchronized with the heap as the heap is manipulated. As a result, PQDict also supports:

• O(1) lookup of an arbitrary element's priority key
• O(log n) removal of an arbitrary element
• O(log n) updating of an arbitrary element's priority key

Why would I want something like that?

Indexed priority queues can be very useful as schedulers for applications like simulations. They can also be used in efficient implementations of Dijkstra's shortest-path algorithm. Basically, whenever we not only want to be able to quickly find the minimum or maximum element, but we also need to be able to dynamically find and modify the priorities of existing elements in the queue efficiently.

Examples

By default, PQDict uses a min-heap, meaning smaller priority keys have higher priority. Use PQDict.maxpq() to create a max-heap priority queue.

.. code:: python

    from pqdict import PQDict

    # same input signature as dict()
    pq = PQDict(a=3, b=5, c=8)
    pq = PQDict(zip(['a','b','c'], [3, 5, 8]))
    pq = PQDict({'a':3, 'b':5, 'c':8})

    # add/update items this way...
    pq.additem('d', 15)
    pq.updateitem('c', 1)

    # ...or this way
    pq['d'] = 6.5
    pq['e'] = 2
    pq['f'] = -5

    # get an element's priority
    pkey = pq['f']
    print pkey          # -5
    print 'f' in pq     # True

    # remove an element and get its priority key
    pkey = pq.pop('f')
    print pkey          # -5
    print 'f' in pq     # False

    pkey = pq.get('f', None)
    print pkey          # None

    # or just delete an element
    del pq['e']

    # peek at the top priority item
    print pq.peek()     # ('c', 1)

    # let's do a manual heapsort
    print pq.popitem()  # ('c', 1)
    print pq.popitem()  # ('a', 3)
    print pq.popitem()  # ('b', 5)
    print pq.popitem()  # ('d', 6.5)

    # and we're empty!
    pq.popitem()        # KeyError

Regular iteration has no prescribed order and is non-destructive.

.. code:: python

    queue = PQDict({'Alice':1, 'Bob':2})
    for customer in queue:
        serve(customer) # Bob may be served before Alice!

This also applies to pq.keys(), pq.values(), pq.items() and using iter().

.. code:: python

    >>> PQDict({'a': 1, 'b': 2, 'c': 3, 'd': 4}).keys()
    ['a', 'c', 'b', 'd']

Destructive iteration methods return generators that pop items out of the heap, which amounts to performing a heapsort:

.. code:: python

    for customer in queue.iterkeys():
        serve(customer) # Customer satisfaction guaranteed :)
    # queue is now empty

The destructive iterators are pq.iterkeys(), pq.itervalues(), and pq.iteritems().

There is also a convenience function to sort a dictionary-like object by value using a PQDict. It is non-destructive and returns a sorted list of dictionary items.

.. code:: python

    from pqdict import heapsorted_by_value

    billionaires = {'Bill Gates': 72.7, 'Warren Buffett': 60.0, ...}
    top10_richest = heapsorted_by_value(billionaires, maxheap=True)[:10]

License

This module was written by Nezar Abdennur and is released under the MIT license. It makes use of some code that was adapted from the Python implementation of the heapq module, which was written by Kevin O'Connor and augmented by Tim Peters and Raymond Hettinger.