Documenting builtin methods
Joshua Landau
joshua at landau.ws
Thu Jul 11 19:11:11 EDT 2013
On 11 July 2013 07:06, Steven D'Aprano <steve at pearwood.info> wrote:
>
> But really, I'm having trouble understanding what sort of application
> would have "run an iterator to exhaustion without doing anything with the
> values" as the performance bottleneck :-)
Definitely not this one. Heck, there's even no real reason something
as appropriately-named as "exhaust_iter" needs documentation.
Largely I was asking because I'd felt I'd missed something more
obvious; it seems there was not. I'm also doing some more functools
stuff than usual -- this method also applies to functions generated
with, say, functools.partial I had guessed. Only it does not, as you
show below -- and functools.partial objects allow you to ineffectively
set .__doc__ anyway.
I also feel that:
def factory():
eatit = deque(maxlen=0).extend
def exhaust_iter(it):
"""Doc string goes here"""
eatit(it)
return exhaust_iter
exhaust_it = factory()
del factory
is a very unobvious way to change a docstring and hides what I'm doing
very effectively. Chris Angelico's method is a fair bit better in this
regard, but I'm not sure it's worth it in this case. One
recommendation with Chris's method is to make it keyword-only (with
"*") which should keep the interface a touch cleaner.
>> exhaust_iter.__doc__ = "Exhaust an iterator efficiently [...]"
>>
>> Obviously it does not work.
>
> Even if it did work, it would not do what you hope. Because __doc__ is a
> dunder attribute (double leading and trailing underscores), help()
> currently looks it up on the class, not the instance:
I'd not considered that, and it seems to have doomed me from the start.
More information about the Python-list
mailing list