Path: csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!gegeweb.org!de-l.enfer-du-nord.net!feeder2.enfer-du-nord.net!feeds.phibee-telecom.net!newsfeed.xs4all.nl!newsfeed6.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail
DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; b=o5GncsvqKvL3O7zFZiGnt4bdgTySHXc5oMOnEznO5F9zy/1+HoiSsZGVpnMkrTciqQ vI/WlnGgHfx5Muem6yn3TZMPOgI6MPtAN3PEEGsi91/rsDpr88cGUgyi7EvroEofVDtp RKmwto/3Wmrfz396JjiYeGltrR8dpnz3Pa8pw=
MIME-Version: 1.0
In-Reply-To: <4DF1FA8B.2020609@tim.thechases.com>
References: <BANLkTin3FGoxwvH2VDOb4OhAWi2Ea3K-pA@mail.gmail.com> <4DF1FA8B.2020609@tim.thechases.com>
Date: Fri, 10 Jun 2011 10:55:24 -0600
Subject: Re: how to inherit docstrings?
From: Eric Snow <ericsnowcurrently@gmail.com>
To: Tim Chase <python.list@tim.thechases.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Cc: python-list <python-list@python.org>
Precedence: list
Newsgroups: comp.lang.python
Message-ID: <mailman.84.1307724926.11593.python-list@python.org>
Lines: 99
NNTP-Posting-Host: 82.94.164.166
Xref: x330-a1.tempe.blueboxinc.net comp.lang.python:7383

On Fri, Jun 10, 2011 at 5:05 AM, Tim Chase
<python.list@tim.thechases.com> wrote:
> On 06/09/2011 01:22 AM, Eric Snow wrote:
>>
>> Sometimes when using class inheritance, I want the overriding methods
>> of the subclass to get the docstring of the matching method in the
>> base class. =A0You can do this with decorators (after the class
>> definition), with class decorators, and with metaclasses [1].
>
> While asking for __doc__ ponies and picking colors for bike-sheds, in a
> similar vein, I've occasionally wanted to do something like
>
> =A0class Foo:
> =A0 =A0@property
> =A0 =A0def __doc__(self):
> =A0 =A0 =A0return dynamically_generated_string
> =A0 =A0 =A0# perhaps using introspection
>

However, on the class the property is just a property object (a
descriptor).  If you want to have a dynamic doc on the class then you
have to do it on a metaclass:

class Meta(type):
    @property
    def __doc__(cls):
        if not hasattr(cls, "_mydoc"):
            cls._mydoc =3D None
        return cls._mydoc

class X(metaclass=3DMeta): pass

X.__doc__
# None
X._mydoc
# None
X._mydoc =3D "test"
X.__doc__
# 'test'
X().__doc__
# None

The only problem, as seen in the last line, is that the __doc__ on
instances is not inherited on instances of the class.  Object
attribute lookup only looks to the type's __dict__ for inheritance,
and not the types's type.  However, that should not be that hard to
work around.

-eric


> This would have been most helpful in things like generating help (like in
> command-line parsers), where the doc-string can introspect the class and
> learn about its methods at runtime. Some things seem to inherit, some don=
't,
> and help() doesn't seem to pick up on any of the dynamically-defined __do=
c__
> properties. =A0Test code below.
>
> -tkc
>
>
>
> from datetime import datetime
> from sys import stdout
> class Base(object):
> =A0"Base docstring"
> =A0@property
> =A0def __doc__(self):
> =A0 =A0return datetime.now().strftime('%c')
>
> class WithDoc(Base):
> =A0"WithDoc docstring"
> =A0pass
>
> class WithoutDoc(Base): pass
>
> base =3D Base()
> has =3D WithDoc()
> lacks =3D WithoutDoc()
>
> for test in (
> =A0"help(base)", # why not in help?
> =A0"help(has)", # expected
> =A0"help(lacks)", # why not in help?
> =A0"help(Base)",
> =A0"help(WithDoc)", # expected
> =A0"help(WithoutDoc)",
> =A0"stdout.write(repr(base.__doc__))", # works
> =A0"stdout.write(repr(has.__doc__))", # expected
> =A0"stdout.write(repr(lacks.__doc__))", # where'd it go?
> =A0"stdout.write(repr(Base.__doc__))", # expected
> =A0"stdout.write(repr(WithDoc.__doc__))", # expected
> =A0"stdout.write(repr(WithoutDoc.__doc__))", # what?
> =A0):
> =A0print test
> =A0eval(test)
> =A0print
>