How do heapq.heappushpop and heapq.heapreplace differ on the same list?

### Two names, one operation, opposite order Both functions exist because doing an insert and a removal as two separate calls does more work than doing them together, and because they cover two different intents. `heapq.heappushpop(heap, item)`: push `item`, then pop and return the smallest. If `item` is already smaller than the current root, pushing it would make it the new root, and popping would immediately take it back out — so the implementation short-circuits, returns `item`, and leaves the list exactly as it was. `heapq.heapreplace(heap, item)`: pop and return the current smallest, then push `item`. There is no short-circuit and no comparison against `item`. The root leaves, `item` goes in, unconditionally. The difference shows up the moment the incoming item is small: ```python import heapq h = [1, 3, 5] heapq.heapreplace(h, 0) # returns 1, heap becomes [0, 3, 5] h2 = [1, 3, 5] heapq.heappushpop(h2, 0) # returns 0, heap stays [1, 3, 5] ``` Same list, same argument, different survivor. Swap one call for the other in code that maintains a bounded collection of the best-so-far and you have changed which element gets discarded — without any error, any warning, or any change in the list's length. ### The docstring's warning, decoded The `heapreplace` docstring says outright that "the value returned may be larger than item" and that this "constrains reasonable uses of this routine unless written as part of a conditional replacement": ```python if item > heap[0]: item = heapq.heapreplace(heap, item) ``` Read that guard carefully: it is the comparison `heappushpop` performs internally. If your guard is exactly this, `heappushpop` is the same operation with one fewer place to make a mistake. `heapreplace` earns its keep when you *want* unconditional eviction — a rolling window where the oldest entry must leave no matter what replaces it, or a case where you have already decided the root is going, independent of the newcomer's value. ### The empty-heap divergence The second, sharper difference: ```python heapq.heappushpop([], 4) # 4 heapq.heapreplace([], 4) # IndexError: index out of range ``` `heapreplace` must pop first, and there is nothing to pop. `heappushpop` pushes first, so there always is. This bites in warm-up code: a loop that calls `heapreplace` from the first iteration crashes on iteration one, while the same loop written with `heappushpop` quietly does the wrong thing instead — it accepts the first item and returns it, so the heap never fills. Neither is a substitute for handling the fill phase explicitly, usually with `heapq.heappush` until the collection reaches its target size and one of these two afterwards. ### Why they exist at all Each performs a single restore pass rather than the two that a separate `heappush` plus `heappop` would do, and neither changes the length of the list. That last property is what makes them the natural pair of calls for anything that must stay a fixed size: the list length is an invariant of the loop rather than something you re-check. One more detail worth knowing: Python 3.14 added `heappushpop_max` and `heapreplace_max` alongside the other max-heap functions, with the same relationship to each other, mirrored. As with all of that family, do not mix them with the min-heap functions on one list — each maintains its own invariant and neither validates the other's. ### How to answer State the operation order, give the small-item example where the return values differ, mention the empty-heap `IndexError`, and finish with the guard from the docstring and the observation that the guard *is* `heappushpop`. That last line is what separates someone who has read the module from someone who has only used it.