heapq.nlargest

Built-in Data Structures

Meaning

heapq.nlargest() returns the n largest elements from any iterable by maintaining a min‑heap of size n. It avoids sorting the entire collection, which saves time and memory when only the top‑k items are required. Use it when you need an efficient top‑k extraction without mutating the original data.

Primary Function

Selection / Top-k extraction

Communicative Purpose

Retrieves the n largest items from a dataset efficiently.

Pattern

heapq.nlargest(number, iterable)

Core Structure

heapq.nlargest(..., ...)

Função primária

Selection / Top-k extraction

Propósito comunicativo

Retrieves the n largest items from a dataset efficiently.

Situações de gatilho

Gaming leaderboards: selecting the top 10 player scores; E‑commerce: finding the most expensive products for a promotion; Sensor data processing: extracting the highest temperature readings from a stream

Contextos

Data analysis scripts, competitive programming, any code using the heapq module for priority queues.

Padrão

heapq.nlargest(number, iterable)

Estrutura central

heapq.nlargest(..., ...)

Slots de substituição

number: int (non-negative), iterable: iterable of comparable items

Colocados típicos

import heapq
sorted()
heapq.nsmallest()
list slicing

Substituições comuns

sorted(iterable
reverse=True)[:number]
heapq.nlargest(number
iterable
key=func)

Erros comuns

Passing a negative number for n: causes ValueError because n must be non-negative.; Forgetting to import heapq: results in NameError when calling heapq.nlargest.; Assuming the result is sorted in ascending order: the function returns descending order, leading to incorrect interpretation of top items.

Similar / contraste

heapq.nsmallest(n, iterable) for smallest items; sorted(iterable)[:n] for largest but less efficient.

Interferências

Coming from C++: may expect std::partial_sort behavior; in Python use heapq.nlargest for efficient top‑k extraction.

Família do chunk

heapq.nsmallest
sorted
list.sort
heapq.heapify

Nuance

Not suitable when you need the original iterable sorted in place or when you require ascending order without additional reversal; performance is O(k log n) time and O(k) extra space, better than full sort O(n log n) for small k; if n exceeds iterable length, returns all items sorted descending, and n==0 yields an empty list.

Efeito pragmático

Provides efficient top-k extraction without full sort, saving time and memory.

Dica de memória

Think 'nlargest' = 'n largest' from heapq.

Nota

Returns a new list in descending order; does not modify the original iterable; works with any iterable; time complexity O(k log n).

Upgrade path

heapq.nlargest(number, iterable, key=func) for custom ordering

Frequência: MediumFormulaicidade: Semi-fixedTipo de construção: function callPrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

import heapq scores = [85, 92, 78, 90, 88] top3 = heapq.nlargest(3, scores) print(top3) # [92, 90, 88]

import heapq products = [{"name":"apple","price":1.2},{"name":"banana","price":0.5},{"name":"cherry","price":2.0}] top2 = heapq.nlargest(2, products, key=lambda p: p["price\]) print(top2) # [{'name':'cherry','price':2.0}, {'name':'apple','price':1.2}]

import heapq, random def random_numbers(): for _ in range(1000000): yield random.random() top5 = heapq.nlargest(5, random_numbers()) print(top5)