Return the n largest elements from an iterable using a heap.

Retrieve the top‑n largest items efficiently without sorting the entire collection.

When you need the top N largest values from a collection (e.g., top scores, highest prices) and want better than O(n log n) performance.

Data analysis, scoring systems, priority queues, finding extremes in large datasets.

heapq\.nlargest\(n, iterable\)

Call to heapq.nlargest with arguments n (number of items) and iterable (any iterable), returning a list of the n largest elements.

n: int ≥ 0, iterable: iterable of comparable items

• heapq.nsmallest
• heapq.heapify
• heapq.heappush
• heapq.heappop

• sorted(iterable
• reverse=True)[:n] (less efficient for large n)
• repeated max removal O(n*k)

Using n larger than the iterable length without checking – returns all items, which may be unexpected if a shorter list was expected. Assuming the result is sorted in descending order; heapq.nlargest returns items in descending order, but if order matters you may need to sort the result. Using a non‑comparable iterable (e.g., mixing strings and numbers) causing a TypeError during heap comparisons.

heapq.nsmallest – returns the n smallest elements instead of the largest. sorted(iterable, reverse=True)[:n] – returns the same result but with O(n log n) time, less efficient for large n. max(iterable) – returns only the single largest element, not a list of top‑n.

Coming from SQL: may rely on ORDER BY … LIMIT n; in Python, heapq.nlargest provides the same result without sorting the whole dataset. Coming from Java: might use Collections.max repeatedly; heapq.nlargest is more efficient for extracting multiple top elements.

• heapq.nlargest
• heapq.nsmallest
• heapq.heapify
• heapq.heappush
• heapq.heappop

Do not use when n is close to the size of the iterable; sorting may be faster. Performance advantage is O(n log k) versus O(n log n) for a full sort. When the iterable is an iterator, heapq.nlargest consumes it eagerly, which could exhaust memory if the iterator is large.

Enables efficient extraction of the top‑k largest elements from large datasets without the overhead of a full sort, reducing runtime and memory usage in scoring, ranking, and priority‑queue scenarios.

Imagine sifting through a handful of gems while keeping only the biggest ones in a small pouch – you never need to sort the whole pile.

If a key function is supplied, the key is applied once per item and cached; if a default is supplied, it is returned when the iterable contains fewer than n items.

heapq.nlargest with a key function or default value