Toolshed: types : XMinHeap

Import XMinHeap

from Naked.toolshed.types import XMinHeap

Import XMinHeap from C Module

from Naked.toolshed.c.types import XMinHeap

The C module must be compiled before you import it. See the naked build documentation for more information.

Description

The XMinHeap class is a min heap priority queue that extends Python heapq. This class supports sorting of new items that are pushed to the queue by assigned priority and pop of the lowest priority item. It also supports the addition of attribute metadata on instantiation of the class.

class Naked.toolshed.types.XMinHeap([attribute_dictionary])
Parameters:attribute_dictionary (dict) – (optional) a Python dictionary that is used to define the attributes of a new instance of a XMinHeap. Key names are mapped to attribute names and their corresponding values are mapped to the attribute values.

Function Overload

__len__()
Returns:(int) returns the number of items in the XMinHeap. This allows you to use len(XMinHeap()) to determine the number of items in the priority queue.

XMinHeap Methods

length()
Returns:(int) returns the number of items in the XMinHeap
pop()

Pops the lowest priority item off of the queue.

Returns:(item type dependent) returns the lowest priority item which is defined as the item that has the lowest item_priority value. If multiple items have the same value, they are returned on a first-in, first-out order (FIFO). If the queue is empty, returns None.
push(queue_item, item_priority)

Pushes an item to the queue with the priority defined

Parameters:
  • queue_item (any) – an object that is added to the priority queue.
  • item_priority (int) – an integer that represents the priority of the item from 1 (min) to x (max). It is possible to assign the same priority level to multiple items in the queue.
pushpop(queue_item, item_priority)

Pushes an item to the queue and immediately pops and returns the lowest priority item off of the queue.

Parameters:
  • queue_item (any) – an object that is added to the priority queue.
  • item_priority (int) – an integer that represents the priority of the item from 1 (min) to x (max). It is possible to assign the same priority level to multiple items in the queue.
Returns:

(item type dependent) returns the lowest priority item which is defined as the item that has the lowest item_priority value. If multiple items have the same value, they are returned on a first-in, first-out order (FIFO). If the item that is pushed to the queue is the lowest priority item, it is immediately returned. If the queue is empty, returns None.

Examples

Create a New Instance of XMinHeap, No Metadata

from Naked.toolshed.types import XMinHeap

xmh = XMinHeap()

Create a New Instance of XMinHeap, With Metadata

from Naked.toolshed.types import XMinHeap

xmh = XMinHeap({'heapnumber': 1})

Access XMinHeap Attribute Data

from Naked.toolshed.types import XMinHeap

xmh = XMinHeap({'heapnumber': 1})
print(xmh.heapnumber) # prints 1

Push Items on to the XMinHeap

from Naked.toolshed.types import XMinHeap

xmh = XMinHeap({'heapnumber': 1})
xmh.push('eat eggs', 1)
xmh.push('eat spam', 2)

Pop Items off of the XMinHeap by Priority

from Naked.toolshed.types import XMinHeap

xmh = XMinHeap({'heapnumber': 1})
xmh.push('eat eggs', 1)
xmh.push('eat spam', 2)
print(xmh.pop()) # prints 'eat eggs'
print(xmh.pop()) # prints 'eat spam'

Priority Tie Handling with XMinHeap

from Naked.toolshed.types import XMinHeap

xmh = XMinHeap({'heapnumber': 1})
xmh.push('eat eggs', 1)
xmh.push('eat spam', 1)  # same priority as above
print(xmh.pop()) # prints 'eat eggs' --> FIFO handling of ties
print(xmh.pop()) # prints 'eat spam'

Simultaneous Push and Pop with XMinHeap

from Naked.toolshed.types import XMinHeap

xmh = XMinHeap({'heapnumber': 1})
xmh.push('eat eggs', 1)
xmh.push('eat spam', 2)
result = xmh.pushpop('buy Chris a coffee', 1)
print(result)      # prints 'eat eggs'
print(xmh.pop())   # prints 'buy Chris a coffee' ;)
print(xmh.pop())   # prints 'eat spam'