Return-Path: <joshua.landau.ws@gmail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.003
X-Spam-Evidence: '*H*': 0.99; '*S*': 0.00; 'anyway.': 0.05; 'say,': 0.05; 'attribute': 0.07; 'class,': 0.07; 'string': 0.09; 'trailing': 0.09; 'cc:addr:python-list': 0.11; 'def': 0.12; 'missed': 0.12; '"run': 0.16; 'docstring': 0.16; 'factory': 0.16; 'hides': 0.16; 'instance:': 0.16; 'iterator': 0.16; 'to:addr:pearwood.info': 0.16; "to:name:steven d'aprano": 0.16; 'applies': 0.16; ':-)': 0.16; 'sender:addr:gmail.com': 0.17; 'wrote:': 0.18; 'obviously': 0.18; 'bit': 0.19; 'not,': 0.20; 'work,': 0.20; 'seems': 0.21; 'cc:addr:python.org': 0.22; 'case.': 0.24; 'looks': 0.24; 'cc:2**0': 0.24; 'sort': 0.25; 'asking': 0.27; 'header:In-Reply-To:1': 0.27; 'chris': 0.29; 'message- id:@mail.gmail.com': 0.30; "i'm": 0.30; 'work.': 0.31; "d'aprano": 0.31; 'really,': 0.31; 'steven': 0.31; 'with,': 0.31; 'stuff': 0.32; 'interface': 0.32; 'not.': 0.33; 'trouble': 0.34; 'skip:d 20': 0.34; "i'd": 0.34; 'something': 0.35; 'objects': 0.35; 'usual': 0.35; 'but': 0.35; 'received:google.com': 0.35; 'there': 0.35; 'largely': 0.36; 'doing': 0.36; 'method': 0.36; 'should': 0.36; 'application': 0.37; 'performance': 0.37; 'that,': 0.38; 'anything': 0.39; 'does': 0.39; 'sure': 0.39; 'even': 0.60; 'skip:u 10': 0.60; 'show': 0.63; 'real': 0.63; 'july': 0.63; 'more': 0.64; 'worth': 0.66; 'felt': 0.74; 'touch': 0.74; 'start.': 0.84; 'regard,': 0.91; '2013': 0.98
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:sender:in-reply-to:references:from:date :x-google-sender-auth:message-id:subject:to:cc:content-type; bh=iRDPA3O5JTlfNKy7VK1mjA2EXm7nddWbhFe6AOW1MW8=; b=rCREMRKb/RCQuZw+D31jF06Bm5JinCEoQ4APFnU3ktTvkpc7JrcKOQC7QsSIrXwA7S GUIrhZ0dRc9lJg1DhoyGGr+w/SpVPpZEtXSGUJfaSKQyeCQAWnRM41K2D87c6kylcCc7 ih5h0jbUG87TQnM+ubvUDl1R6OBTfc6H9rUC8B1zbP9TZtJbETGlUoG61i0aHYPlEVOn U8HcjsbtU417erkh/vgC4Glej/Su6UCYwQ3YwRG7cCjChaEnkTo4YriOJqXkC6mzltYV MCuSR1CQUPmaT1oj/n5NZklWoW/OGmMxhRXmQMneA2E0TxGieqPyfEXZ6xQjE03g5tOK 8t5g==
X-Received: by 10.152.20.40 with SMTP id k8mr18695885lae.25.1373584311980; Thu, 11 Jul 2013 16:11:51 -0700 (PDT)
MIME-Version: 1.0
Sender: joshua.landau.ws@gmail.com
In-Reply-To: <51de4b6c$0$11094$c3e8da3@news.astraweb.com>
References: <mailman.4558.1373512579.3114.python-list@python.org> <51de4b6c$0$11094$c3e8da3@news.astraweb.com>
From: Joshua Landau <joshua@landau.ws>
Date: Fri, 12 Jul 2013 00:11:11 +0100
X-Google-Sender-Auth: 5aMlYg7yTY8h7fS7fDie2tlqPKM
Subject: Re: Documenting builtin methods
To: "Steven D'Aprano" <steve@pearwood.info>
Content-Type: text/plain; charset=UTF-8
Cc: python-list <python-list@python.org>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <http://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list/>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <http://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.4603.1373584321.3114.python-list@python.org>
Lines: 43
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1373584321 news.xs4all.nl 15901 [2001:888:2000:d::a6]:48479
X-Complaints-To: abuse@xs4all.nl
Path: csiph.com!usenet.pasdenom.info!news.stben.net!border3.nntp.ams.giganews.com!border1.nntp.ams.giganews.com!nntp.giganews.com!xlned.com!feeder5.xlned.com!newsfeed.xs4all.nl!newsfeed3.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail
Xref: csiph.com comp.lang.python:50477

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.