Top-k selection

Retrieves the k smallest elements efficiently without full sorting

Data analysis: extracting the lowest scores from a large survey dataset Performance-critical code: getting the smallest elements from a stream without sorting the entire input Algorithm implementation: selecting k-nearest neighbors by distance in a machine learning pipeline

Python data processing, algorithmic competitions, scientific computing

heapq.nsmallest(count, items, key=key_func)

heapq.nsmallest(..., ...)

count: int >= 0, items: iterable, key_func: callable (optional)

• Often used with lists
• tuples
• or generators
• combined with lambda or operator.itemgetter for key
• frequently followed by list() conversion if needed.

• sorted(iterable)[:k] — simple but O(n log n) time and O(n) memory
• heapq.nlargest for largest elements
• manual heap push/pop — more control over ordering.

Using key as a positional argument (heapq.nsmallest(count, items, key_func)) causes TypeError because key must be a keyword argument.; Forgetting to import heapq leads to NameError when calling heapq.nsmallest.; Passing a non-integer or negative count results in TypeError or unexpected empty list.; Providing a key function that returns non-comparable types (e.g., mixing str and int) raises TypeError during comparison.; Assuming the result is sorted in ascending order; heapq.nsmallest returns items in sorted order, but if you need original order you must sort again.

heapq.nlargest — returns largest elements; sorted() — returns fully sorted list; min() — returns single smallest element; max() — returns single largest element.

Coming from Java: may expect Collections.nthElement to modify the list in-place — heapq.nsmallest returns a new list and leaves the original unchanged.

• heapq.nlargest
• sorted
• min
• max

Avoid using heapq.nsmallest when you need the elements in their original order, as it returns them sorted; for large k close to n, sorting the whole iterable may be more efficient due to lower overhead; if the iterable is not sized (e.g., a generator), the function consumes it entirely to build the heap, so it cannot be used on infinite streams.

Enables efficient extraction of top-k from large datasets without excessive memory or CPU, making it suitable for real-time analytics and large-scale data processing.

Like using a magnet to pick out the smallest nails from a haystack without sorting the whole pile.

The key function, if provided, is applied exactly once per element and its results are cached for comparisons.

heapq.nlargest