The documentation for heapq.nsmallest and heapq.nlargest: http://docs.python.org/3.3/library/heapq.html#heapq.nlargest claim that they accept three arguments: n, iterable, and key=None. In fact, the implementations of both these functions only accept two parameters: n and iterable. I assume the right thing to do here is to remove the erroneous documentation, rather than implement this apparently-not-needed feature?
The docs are correct as-is. This is a documented and tested behavior. >>> from heapq import nsmallest >>> list(nsmallest(3, ['larry', 'georg', 'raymond', 'guido', 'tim'], key=len)) ['tim', 'larry', 'georg'] The C implementation doesn't have a key-argument. That behavior gets added downstream in pure python in Lib/heapq.py which wraps the C-function and adds the additional behavior.
