Path: csiph.com!x330-a1.tempe.blueboxinc.net!newsfeed.hal-mli.net!feeder1.hal-mli.net!weretis.net!feeder4.news.weretis.net!newsfeed.kpn.net!pfeed08.wxs.nl!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 :content-type:content-transfer-encoding; b=D36nQzUC5QJ1CFSTeEBEHRJrAkG5LeWYEeCEQycjDs1PjpHRF+rk7iBvDWjgSycBjc UjEDJlTaVOI3ZB0dwoP8655m9jBfbJdOwMVBin7RDQ5tnzGZ0s9HNt4QrxG1cDkD7B3h 13dZduRvXwAEa/jEUkTz01heFlKVvfMyIVFdE=
MIME-Version: 1.0
In-Reply-To: <BANLkTin3FGoxwvH2VDOb4OhAWi2Ea3K-pA@mail.gmail.com>
References: <BANLkTin3FGoxwvH2VDOb4OhAWi2Ea3K-pA@mail.gmail.com>
Date: Fri, 10 Jun 2011 17:25:28 -0600
Subject: Re: how to inherit docstrings?
From: Eric Snow <ericsnowcurrently@gmail.com>
To: python-list <python-list@python.org>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Precedence: list
Newsgroups: comp.lang.python
Message-ID: <mailman.116.1307748335.11593.python-list@python.org>
Lines: 90
NNTP-Posting-Host: 82.94.164.166
Xref: x330-a1.tempe.blueboxinc.net comp.lang.python:7419

On Thu, Jun 9, 2011 at 12:22 AM, Eric Snow <ericsnowcurrently@gmail.com> wr=
ote:
> 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].
>
> However, I was hoping for a way to do it with just function decorators
> on the methods (no metaclass or class decorator). =A0I am not sure if
> this is doable. =A0I realize now that this is exactly the reason I got
> to thinking last week about objects being notified when they are bound
> [2].
>
> So, is there a way to do this with just decorators, or am I "stuck"
> with the metaclass/class decorator route? =A0(It's not all that bad :)
>

Thanks for all the feedback on this thread everyone!  I found a
solution that works pretty well, using descriptors:

    class DocFunc:

        TRIGGER =3D None

        def __init__(self, f):
            self.f =3D f

        def __get__(self, obj, cls):
            doc =3D self.f.__doc__
            if doc =3D=3D self.TRIGGER:
                doc =3D self.get_doc(cls, self.f.__name__, self.TRIGGER)
            self.f.__doc__ =3D doc
            setattr(cls, self.f.__name__, self.f)
            return self.f

        @staticmethod
        def get_doc(cls, fname, default=3DTRIGGER, member=3DTrue):
            bases =3D cls.__mro__[:]
            if member:
                bases =3D bases[1:]
            for base in bases:
                func =3D getattr(base, fname, None)
                if not func:
                    continue
                doc =3D getattr(func, '__doc__', default)
                if doc =3D=3D default:
                    continue
                return doc
            return default

        @staticmethod
        def inherits_docstring(f, context=3DNone, fname=3DNone, default=3DT=
RIGGER):
            if context is not None:
                cls, namespace =3D context
                fname =3D fname or f.__name__
                f.__doc__ =3D DocFunc.get_doc(cls, fname, default, False)
                return f
            return DocFunc(f)

    class X:
        def something(self):
            """some method"""

    class Y(X):
        @DocFunc.inherits_docstring
        def something(self):
            ...

This approach does not update the docstring if it changes in the base
class, but I don't need that for what I am doing.  If you want to
trigger on an empty string, instead of None, just change the TRIGGER.

-eric


> Thanks!
>
> -eric
>
>
> p.s. Am I missing something or can you really not change the docstring
> of a class? =A0I was thinking about the idea of inheriting class
> docstrings too.
>
>
> [1] http://code.activestate.com/recipes/577743-using-decorators-to-inheri=
t-function-docstrings/
> [2] http://mail.python.org/pipermail/python-ideas/2011-June/010446.html
>