How to Use heapq Module in Python: Syntax and Examples
The
heapq module in Python provides functions to create and manipulate heaps, which are binary trees where the smallest element is always at the root. You can use heapq.heapify() to convert a list into a heap, and heapq.heappush() and heapq.heappop() to add and remove the smallest elements efficiently.Syntax
The heapq module offers these main functions:
heapq.heapify(list): Converts a list into a heap in-place.heapq.heappush(heap, item): Adds an item to the heap, maintaining heap order.heapq.heappop(heap): Removes and returns the smallest item from the heap.heapq.heappushpop(heap, item): Pushes a new item and pops the smallest item in one operation.heapq.heapreplace(heap, item): Pops the smallest item and pushes a new item.
Heaps are always represented as lists.
python
import heapq # Create a list numbers = [5, 7, 9, 1, 3] # Convert list to heap heapq.heapify(numbers) # Add an element heapq.heappush(numbers, 4) # Remove smallest element smallest = heapq.heappop(numbers)
Example
This example shows how to create a heap, add elements, and remove the smallest element step-by-step.
python
import heapq numbers = [20, 15, 10, 5, 30] print("Original list:", numbers) heapq.heapify(numbers) print("Heapified list:", numbers) heapq.heappush(numbers, 12) print("After pushing 12:", numbers) smallest = heapq.heappop(numbers) print("Smallest element popped:", smallest) print("Heap after popping:", numbers)
Output
Original list: [20, 15, 10, 5, 30]
Heapified list: [5, 15, 10, 20, 30]
After pushing 12: [5, 12, 10, 20, 30, 15]
Smallest element popped: 5
Heap after popping: [10, 12, 15, 20, 30]
Common Pitfalls
Common mistakes when using heapq include:
- Forgetting to call
heapify()before using heap operations on a normal list. - Assuming the heap is sorted; it only guarantees the smallest element is at the front.
- Using
heappop()on an empty heap causes anIndexError. - Modifying the heap list directly without using heap functions breaks the heap property.
python
import heapq # Wrong: Using heappop on a normal list without heapify numbers = [3, 1, 4] # smallest = heapq.heappop(numbers) # This will NOT pop the smallest correctly # Right way: heapq.heapify(numbers) smallest = heapq.heappop(numbers) print(smallest) # Outputs 1
Output
1
Quick Reference
| Function | Description |
|---|---|
| heapq.heapify(list) | Convert list into a heap in-place |
| heapq.heappush(heap, item) | Add item to heap maintaining order |
| heapq.heappop(heap) | Remove and return smallest item |
| heapq.heappushpop(heap, item) | Push item then pop smallest item |
| heapq.heapreplace(heap, item) | Pop smallest item then push new item |
Key Takeaways
Use heapq.heapify() to turn a list into a heap before heap operations.
heapq maintains the smallest element at the front for efficient access.
Always use heapq functions to modify the heap to keep its order intact.
heappop() removes the smallest element; heappush() adds a new one.
Avoid using heapq functions on empty heaps to prevent errors.