Path: csiph.com!usenet.pasdenom.info!news.albasani.net!newsfeed.freenet.ag!news2.euro.net!newsfeed.xs4all.nl!newsfeed3.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail
Return-Path: <dreamingforward@gmail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.057
X-Spam-Evidence: '*H*': 0.89; '*S*': 0.00; '(even': 0.05; 'cc:addr :python-list': 0.11; 'caching': 0.16; 'collections': 0.16; 'deque': 0.16; 'docstrings': 0.16; 'iterator': 0.16; 'obviously': 0.18; 'import': 0.22; 'cc:addr:python.org': 0.22; 'creating': 0.23; 'cc:2**0': 0.24; 'class.': 0.26; 'code:': 0.26; 'header:In- Reply-To:1': 0.27; 'message-id:@mail.gmail.com': 0.30; 'work.': 0.31; '(which': 0.31; 'class': 0.32; 'extend': 0.32; 'skip:d 20': 0.34; 'received:google.com': 0.35; 'there': 0.35; 'method': 0.36; 'rather': 0.38; 'does': 0.39; 'how': 0.40; 'new': 0.61; 'simply': 0.61; 'simple': 0.61; 'specialize': 0.74; 'yielded': 0.84; 'canonical': 0.91; 'inefficient': 0.91
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type; bh=YsD2k8PtZ/9IFwAVdmXfRtMKMEue4hSEaiID8kQtgkc=; b=L5Ew5c82GKLj27Z+IGfCiEfEoQfAEOYxqwtXGYKfwQDDnKy6pVJAJQstyOxlCsZo4t UEbFgUrwWcuqSp6bGXjiNr3EXOCbQ4wEbTwcPWz4HAwtTzSXahdKcwb9CV6vIzZ17ijD KWqq0eZvKciH2QxbvxNYs9OTak3rupCZKjsSf6JeAaNPuGWOs1pbVKMqgykvq4tSaxnr BzndIMAf1Q4IPfaj4EBEBTrCv4oKHQ+Szv3vBmZ9FXQfWMJlNbCzQjNUEA/nsgYhfTpS AMVvsMam5e8+WwFw1QjnlyBmClPNpcSaAID3hf8fTa/0CIybfJNHiS2NqP+0HTZ97Kkr 5Q9Q==
MIME-Version: 1.0
X-Received: by 10.194.121.132 with SMTP id lk4mr19943729wjb.25.1373513354324; Wed, 10 Jul 2013 20:29:14 -0700 (PDT)
In-Reply-To: <CAN1F8qVbECK_xsH-umbdzw1WfUv=y2K0Poy6Yj=q5OWBpEjavA@mail.gmail.com>
References: <CAN1F8qVbECK_xsH-umbdzw1WfUv=y2K0Poy6Yj=q5OWBpEjavA@mail.gmail.com>
Date: Wed, 10 Jul 2013 20:29:14 -0700
Subject: Re: Documenting builtin methods
From: Mark Janssen <dreamingforward@gmail.com>
To: Joshua Landau <joshua@landau.ws>
Content-Type: text/plain; charset=ISO-8859-1
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.4559.1373513356.3114.python-list@python.org>
Lines: 17
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1373513356 news.xs4all.nl 15917 [2001:888:2000:d::a6]:48896
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:50406

> 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?

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.

markj