Priority Queue in Python

When I first started programming with Python over a decade ago, one of the data structures that immediately stood out for its efficiency and versatility was the priority queue. Whether you’re managing tasks, scheduling jobs, or handling real-time events, priority queues help you process items based on their importance rather than just arrival order.

In this guide, I’ll share my firsthand experience with priority queues in Python. I’ll walk you through what a priority queue is, how to implement one using Python’s built-in modules, and practical examples that you can use in your own projects. By the end, you’ll confidently harness Python’s priority queue capabilities for your applications.

Table of Contents

What Is a Priority Queue in Python?

A priority queue is a special type of queue where each element is associated with a priority. Unlike regular queues that operate in a first-in-first-out (FIFO) manner, priority queues serve elements based on their priority level, the highest priority elements get processed first.

In Python, priority queues are often implemented using the heapq module, which provides an efficient min-heap data structure. This means the smallest element (by priority) is always at the front of the queue.

Use a Priority Queue in Python

In many real-world applications in the USA, such as task scheduling in operating systems, event-driven simulations, or managing customer support tickets, you need to process important tasks before less critical ones.

Python’s priority queue helps:

Manage tasks efficiently by priority.
Handle dynamic data where priorities can change.
Optimize performance with O(log n) insertion and removal.

Method 1: Implemente a Priority Queue Using heapq

The heapq module is the go-to solution in Python for priority queues. Here’s a simple example to show how I use it:

import heapq

# Create an empty priority queue (min-heap)
priority_queue = []

# Push tasks with priority
heapq.heappush(priority_queue, (2, "Write report"))
heapq.heappush(priority_queue, (1, "Fix critical bug"))
heapq.heappush(priority_queue, (3, "Email client"))

# Pop tasks by priority
while priority_queue:
    priority, task = heapq.heappop(priority_queue)
    print(f"Processing task: {task} with priority {priority}")

Output:

Processing task: Fix critical bug with priority 1
Processing task: Write report with priority 2
Processing task: Email client with priority 3

You can refer to the screenshot below to see the output.

In this example, the task with the lowest priority number (1) is processed first. This approach is simple and efficient for many use cases.

Method 2: Use queue.PriorityQueue for Thread-Safe Priority Queues

If your Python application involves multithreading, the queue.PriorityQueue class is a thread-safe implementation of a priority queue.

Here’s how I use it:

from queue import PriorityQueue

pq = PriorityQueue()

# Add tasks with priority
pq.put((2, "Complete project plan"))
pq.put((1, "Respond to urgent emails"))
pq.put((3, "Schedule meeting"))

# Process tasks
while not pq.empty():
    priority, task = pq.get()
    print(f"Handling task: {task} with priority {priority}")

Output:

Handling task: Respond to urgent emails with priority 1
Handling task: Complete project plan with priority 2
Handling task: Schedule meeting with priority 3

You can refer to the screenshot below to see the output.

This method is perfect when you need safe access to the queue across multiple threads.

Method 3: Custom Priority Queue Class with Python’s heapq

For more control, I sometimes create a custom priority queue class encapsulating heapq operations. This makes the code cleaner and reusable.

import heapq

class PriorityQueue:
    def __init__(self):
        self._queue = []
        self._index = 0

    def push(self, item, priority):
        # Use index to maintain FIFO order among same priority items
        heapq.heappush(self._queue, (priority, self._index, item))
        self._index += 1

    def pop(self):
        return heapq.heappop(self._queue)[-1]

# Example usage
pq = PriorityQueue()
pq.push("Pay bills", 2)
pq.push("Buy groceries", 3)
pq.push("Call plumber", 1)

while True:
    try:
        task = pq.pop()
        print(f"Next task: {task}")
    except IndexError:
        break

Output:

Next task: Call plumber
Next task: Pay bills
Next task: Buy groceries

You can refer to the screenshot below to see the output.

The index ensures that if two tasks share the same priority, they are processed in the order they were added.

Practical Use Case: Manage Customer Support Tickets

In customer support systems in the USA, tickets are often prioritized by urgency. Using Python’s priority queue, you can efficiently manage and process tickets.

tickets = PriorityQueue()
tickets.put((1, "Server down"))
tickets.put((3, "Password reset"))
tickets.put((2, "Billing issue"))

while not tickets.empty():
    priority, ticket = tickets.get()
    print(f"Processing ticket: {ticket} with priority {priority}")

Output:

Processing ticket: Server down with priority 1
Processing ticket: Billing issue with priority 2
Processing ticket: Password reset with priority 3

This ensures urgent problems get immediate attention.

Tips for Using Priority Queues in Python

Use tuples (priority, item) to store data, so priority determines order.
Remember that heapq implements a min-heap by default.
For max-priority queues, invert the priority by storing negative values.
Consider thread safety if your app involves concurrency — use queue.PriorityQueue.
Use custom classes for complex data handling and better code organization.

Common Mistakes to Avoid

Forgetting that heapq does not automatically support max-heaps.
Using mutable objects as priorities, which can cause unpredictable behavior.
Not maintaining insertion order for items with equal priority (use an index).
Mixing up heapq and queue.PriorityQueue — the latter is thread-safe but slower.

Mastering priority queues in Python has significantly improved how I manage tasks and data in my projects. Whether you’re building a scheduler, a real-time system, or a task manager, Python’s priority queue tools are indispensable.

Experiment with the examples above, and tailor them to your needs. With this knowledge, you’ll write efficient, clean Python code that prioritizes tasks intelligently.