API Reference — pqdict 0.5.0 documentation

- Quick links
- GitHub
- Issues
- ·
- ·
- Follow @nv1ctus
- Tweet

# API Reference

## `PQDict` class

class `pqdict.` `PQDict`(*args, **kwargs)

  A mapping object that maps dictionary keys (dkeys) to priority keys (pkeys). PQDicts maintain an internal heap so that the highest priority item can always be obtained in constant time. The mapping is mutable so items may be added, removed and have their priorities updated without breaking the heap.

  classmethod `minpq`(*args, **kwargs)

    Create a new Min-PQDict. Smaller priority keys confer higher rank.

  classmethod `maxpq`(*args, **kwargs)

    Create a new Max-PQDict. Larger priority keys confer higher rank.

  classmethod `create`(prio)

    Create an empty PQDict that uses a custom comparator. The comparator should have the form:

    > prio( self, other ) –> bool

    where self and other are entry instances (have dkey and pkey members). The function should return True if self has higher priority than other and False otherwise.

    If prio is a PQDict instance instead of a function, then an empty PQDict using the same comparator is returned.

  classmethod `fromkeys`(iterable, value=None, rank_by=None, maxpq=False)

    Create a new PQDict with dictionary keys from an iterable and priority keys set to value (default value is +inf or -inf to start items off at the bottom of the queue). If a function rank_by is provided instead, that function is used to compute a priority key for each object in the iterable.

### Dictionary Methods

> These should work as expected. See `dict` for more details.

> `len`(pq)
> `pq[dkey]`
> `pq[dkey] = pkey`
> `del pq[dkey]`
> `dkey in pq`
> `PQDict.` `keys`()
> `PQDict.` `values`()
> `PQDict.` `items`()
> `PQDict.` `get`(dkey[, default])
> `PQDict.` `clear`()
> `PQDict.` `update`([other])
> `PQDict.` `setdefault`(dkey[, default])
> `PQDict.` `copy`()

>   Return a new PQD containing the same dkeys associated with the same priority key values.

### Priority Queue Methods

> `PQDict.` `prioritykeys`()

>   Equivalent to `values()`

> `PQDict.` `top`()

>   Get the top priority dictionary key. Raises KeyError if PQD is empty.

> `PQDict.` `pop`([dkey[, default]])

>   If dkey is in the PQD, remove it and return its priority key, else return default. If default is not provided and dkey is not in the PQD, raise a KeyError.

>   If dkey is not provided, remove and return the top-priority dictionary key or raise KeyError if the PQD is empty.

> `PQDict.` `additem`(dkey, pkey)

>   Add a new item. Raises KeyError if dkey is already in the PQD.

> `PQDict.` `updateitem`(dkey, new_pkey)

>   Update the priority key of an existing item. Raises KeyError if dkey is not in the PQD.

> `PQDict.` `topitem`()

>   Get top priority dictionary key and priority key. Raises KeyError if PQD is empty.

> `PQDict.` `popitem`()

>   Extract top priority dictionary key and priority key. Raises KeyError if PQD is empty.

> `PQDict.` `pushpopitem`(dkey, pkey)

>   Equivalent to inserting a new item followed by removing the top priority item, but faster. Raises KeyError if the new dkey is already in the PQD.

> `PQDict.` `replace_key`(dkey, new_dkey)

>   Replace the dictionary key of an existing heap entry in place. Raises KeyError if the dkey to replace does not exist or if the new dkey is already in the PQD.

> `PQDict.` `swap_priority`(dkey1, dkey2)

>   Fast way to swap the priorities of two items in the PQD. Raises KeyError if either dictionary key does not exist.

### Iteration

> `iter`(pq)

>   Returns an iterator over the dictionary keys of the PQD.

>   WARNING: The order of iteration is arbitrary!

> `PQDict.` `iterkeys`()

>   Destructive heapsort iterator over dictionary keys, ordered by priority key.

> `PQDict.` `itervalues`()

>   Destructive heapsort iterator over priority keys.

> `PQDict.` `iteritems`()

>   Destructive heapsort iterator over items, ordered by priority key.

> `PQDict.` `iterprioritykeys`()

>   Equivalent to `itervalues()`

## Functions

`pqdict.` `sort_by_value`(mapping, reverse=False)

  Takes a mapping and, treating the values as priority keys, sorts its items by value via heapsort using a PQDict.

  Equivalent to: sorted(mapping.items(), key=itemgetter(1), reverse=reverse), except it returns a generator.

  Returns:
    an iterator over the dictionary items sorted by value

`pqdict.` `nsmallest`(n, mapping)

  Takes a mapping and returns the n keys with the smallest values.

  Returns:
    a list of n dictionary keys

`pqdict.` `nlargest`(n, mapping)

  Takes a mapping and returns the n keys with the largest values.

  Returns:
    a list of n dictionary keys

`pqdict.` `consume`(*pq_dicts)

  Combine multiple priority queue dictionaries into a single prioritized output stream. Assumes all the priority queues use the same comparator and all priority keys are comparable.

  Returns:
    a generator that yields (dkey, pkey) pairs from all the PQDs