Documenting builtin methods using python

Question

I have this innocent and simple code:

from collections import deque
exhaust_iter = deque(maxlen=0).extend
exhaust_iter.__doc__ = "Exhaust an iterator efficiently without caching any of its yielded values."

Obviously it does not work. Is there a way to get it to work simply and without creating a new scope (which would be a rather inefficient a way to set documentation, and would hamper introspection)?

How about dropping the "simply" requirement?

Answer 1

I think the canonical way to specialize a class (even if it's only docstrings or method re-names) is to extend it with a new class.

Answer 2

I would just go with the most obvious approach:

 def exhaust_iter(iter):
 """
 Exhaust an iterator efficiently without caching
 any of its yielded values
 """
 deque(maxlen=0).extend(iter)

It's not going to be that inefficient unless you're calling it in a long inner loop.