Priority Queue in Python: heapq and a Stable Tie-Break Counter

Start with a small, explicit task

Queue three fictional document jobs: two checks share priority one, and one mail job has priority two. Treat lower numbers as earlier service by an explicit rule. Drain the heap and check both priority ordering and insertion order within the tied checks.

Run the complete example

This original example was checked with Python 3.12.14. Save it as python_priority_queue.py and run it with Python 3.12. It uses only the standard library. The assertions check the stated results.

import heapq
from itertools import count
queue = []
sequence = count()
incoming = [
    (2, {"job": "mail"}),
    (1, {"job": "check-A"}),
    (1, {"job": "check-B"}),
]
for priority, payload in incoming:
    heapq.heappush(queue, (priority, next(sequence), payload))
served = []
while queue:
    priority, order, payload = heapq.heappop(queue)
    served.append((priority, payload["job"]))
assert served == [(1, "check-A"), (1, "check-B"), (2, "mail")]
assert queue == []
print(served)

Explain the result

The two priority-one jobs are removed before mail even though mail arrived first. The sequence numbers preserve check-A before check-B. Tuple comparison stops before reaching the payload because every sequence number is unique, so Python never needs to order the two dictionaries directly.

Popping repeatedly produces the service order; the internal heap list itself is not a completely sorted report. This distinction matters if you inspect queue between operations. The drain loop checks emptiness before each pop, avoiding an empty-heap operation in this finite example. No worker threads or asynchronous execution are involved.

Avoid these mistakes

Do not reuse a tie-break counter value for entries whose payloads cannot be ordered. Keep the priority rule explicit: this is a min-heap, so larger numbers do not automatically mean earlier service. heapq alone does not provide blocking coordination for concurrent producers and consumers; choose a suitable synchronized queue when that is the actual requirement.