Meaning
Adds an item to a heap while preserving the heap property, allowing efficient retrieval of the smallest element. This avoids O(n) insertion cost of a plain list and enables O(log n) push and pop operations. Use when you need a priority queue or repeatedly extract the minimum (or maximum with negation) from a dynamic collection.
Primary Function
Priority queue
Communicative Purpose
Enables efficient O(log n) insertion into a priority queue by maintaining the heap invariant.
Pattern
heapq.heappush(heap, item)
Core Structure
heapq.heappush(..., ...)
Função primária
Priority queue
Propósito comunicativo
Enables efficient O(log n) insertion into a priority queue by maintaining the heap invariant.
Situações de gatilho
Algorithm implementation: implementing Dijkstra's shortest path algorithm Data processing: maintaining a priority queue for event simulation
Contextos
Python standard library, competitive programming, algorithmic libraries, simulation systems
Padrão
heapq.heappush(heap, item)
Estrutura central
heapq.heappush(..., ...)
Slots de substituição
heap: list (must be a heap-ordered list), item: any object that supports ordering with <
Colocados típicos
- heapq.heappop for removal
- heapq.heapify to transform a list into a heap
- using (priority
- value) tuples for prioritized items
Substituições comuns
- queue.PriorityQueue for thread-safe priority queue (higher overhead
- synchronization)
- manual binary heap implementation (more control
- more code)
- sorted list with bisect.insort (O(n) insertion)
Erros comuns
Forgetting to heapify the list before pushing (cause: assuming list is already a heap; consequence: heap property broken, incorrect pops) Pushing non-comparable items (cause: items lack ordering; consequence: TypeError during comparison) Using heapq.heappush on a tuple list without ensuring the first element represents priority (cause: heap compares tuples lexicographically; consequence: unexpected ordering)
Similar / contraste
heapq.heappop: removes and returns the smallest item heapq.heapify: transforms a list into a heap in linear time queue.PriorityQueue: thread-safe priority queue class
Interferências
Coming from Java: may assume PriorityQueue is a class and forget to use heapq module functions → Use heapq functions on a list
Família do chunk
- heapq.heappop
- heapq.heapify
- heapq.merge
Nuance
Do not use when you need a max-heap without negating values (use negative numbers or custom comparator) Each push operation is O(log n) time and O(1) extra space If the heap contains mutable objects that change after insertion, the heap invariant may be violated
Efeito pragmático
Enables efficient priority queue operations, critical for algorithms like Dijkstra's and A* where performance scales with log n rather than linear scan.
Dica de memória
Think of heapq.heappush as tossing a new item onto a sorted pile that automatically reshuffles to keep the smallest on top.
Nota
The heap invariant assumes the list elements are comparable; inserting incomparable items raises TypeError. The heap is a min‑heap; to obtain max‑heap behavior, negate the priority (or supply a custom comparator).
Upgrade path
Using heapq.heappop to retrieve items, or heapq.merge to combine multiple sorted iterables
Log in to save chunks.