Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #50477

Re: Documenting builtin methods

Show key headers only | View raw

On 11 July 2013 07:06, Steven D'Aprano <steve@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.

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

Documenting builtin methods Joshua Landau <joshua@landau.ws> - 2013-07-11 04:15 +0100
  Re: Documenting builtin methods alex23 <wuwei23@gmail.com> - 2013-07-11 15:35 +1000
  Re: Documenting builtin methods Steven D'Aprano <steve@pearwood.info> - 2013-07-11 06:06 +0000
    Re: Documenting builtin methods Chris Angelico <rosuav@gmail.com> - 2013-07-11 17:06 +1000
      Re: Documenting builtin methods Steven D'Aprano <steve@pearwood.info> - 2013-07-11 07:15 +0000
        Re: Documenting builtin methods Chris Angelico <rosuav@gmail.com> - 2013-07-11 17:23 +1000
    Re: Documenting builtin methods Joshua Landau <joshua@landau.ws> - 2013-07-12 00:11 +0100
      Re: Documenting builtin methods alex23 <wuwei23@gmail.com> - 2013-07-12 13:43 +1000
        Re: Documenting builtin methods Joshua Landau <joshua@landau.ws> - 2013-07-12 08:09 +0100

csiph-web