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?

Yes.  Probably someone wished they would implement it :)

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.

I see, there are two "def nsmallest" in heapq.py.  Tricky!