heapq and Priority Access

### There is no heap object The first thing to say out loud in an interview is that `heapq` gives you *functions*, not a type. `heapq.heapify(data)` rearranges the existing `list` in place and returns `None`; `heapq.heappush(data, item)` appends and restores the invariant; `heapq.heappop(data)` removes and returns `data[0]`. The container stays a plain `list` the whole time, which is why you can `len()` it, slice it, pickle it or pass it to a function that has never heard of `heapq`. It also means nothing stops you from mutating that list behind the module's back — `data.append(x)` or `data.sort(reverse=True)` leaves an object that still looks like a list but no longer satisfies what the next `heappop` assumes, and you get silently wrong results rather than an exception. The invariant the module maintains is one-sided: **the smallest element is at index 0**. Nothing else is ordered. A common beginner claim is that `heapify` sorts the list, or that `data[-1]` is the maximum. Neither is true; only position 0 carries a guarantee. ### Why min-only, and the three ways around it The module was written around a single ordering direction and, until recently, exposed only that. So for largest-first access you pick one of three tools. **1. Negation.** Push the arithmetic negative of the ordering key and undo it on the way out: ```python import heapq largest_first = [] for score in (5, 1, 9): heapq.heappush(largest_first, -score) top = -heapq.heappop(largest_first) # 9 ``` With payloads you negate only the priority field of the entry tuple: `heapq.heappush(h, (-priority, item))`. The limitation is that this is real arithmetic. `-"gene"` and `-datetime.date.today()` both raise `TypeError`, so for non-numeric orderings you either derive a numeric surrogate (a negated POSIX timestamp, a negated code point sequence) or wrap the value in a small class whose `__lt__` is inverted. **2. `heapq.nlargest` / `heapq.nsmallest`.** When you want an answer rather than a live structure, `heapq.nlargest(3, data)` and its `key=` parameter give you the result directly and you never touch a heap at all. This is the right call for a one-pass question over a finite iterable; it is the wrong call when items keep arriving and you must pop as you go. **3. The 3.14 max-heap functions.** Python 3.14 promoted the module's long-standing private max-heap helpers to public names: `heapify_max`, `heappush_max`, `heappop_max`, `heapreplace_max` and `heappushpop_max`. They maintain the mirror invariant — largest at index 0 — over the same ordinary list: ```python import heapq readings = [5, 1, 9] heapq.heapify_max(readings) readings[0] # 9 heapq.heappop_max(readings) # 9 ``` On 3.13 and earlier those names do not exist; code that must run on older interpreters uses negation. And the two families are not interchangeable on one list: a list built with `heappush` satisfies the min invariant, and calling `heappop_max` on it returns garbage without complaining. ### What interviewers are really checking Three things. First, that you know the container is a list and the module is a set of functions over it — candidates who reach for a nonexistent `heapq.Heap()` or pass `reverse=True` have never used it. Second, that you can state the invariant precisely: index 0 only. Third, that you pick the right one of the three tools for the shape of the problem — a live priority structure wants a heap, a one-shot ranking wants `nlargest`, and a portable max-heap on an older interpreter wants negation. A useful closing detail: `heapq.heapify` works on any list you already have, so the usual pattern is to build the list however you like and heapify once, rather than pushing elements one at a time. And if you find yourself needing both directions over the same data at once, that is a signal you want two structures, not one clever encoding.