Path: csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!aioe.org!feeder.news-service.com!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=iMXRDZlulSZ9wOWd9K+24gf6RBuG38O2ws1lTzYW0fJBY0uduQh2tz+J/t1pXZqhCV g/W8TlnfJOWczWg3ym63zmSLBNAqK8Sg/E3fZvgOBQCOQyurnLQFs9aNhV2e7P2i9la9 76YtWMMaVmrgDJLY6jpNvaqF/NXZeD2VxfVpU=
MIME-Version: 1.0
In-Reply-To: <4df24a87$0$30002$c3e8da3$5496439d@news.astraweb.com>
References: <mailman.42.1307600576.11593.python-list@python.org> <4df24a87$0$30002$c3e8da3$5496439d@news.astraweb.com>
Date: Fri, 10 Jun 2011 11:01:41 -0600
Subject: Re: how to inherit docstrings?
From: Eric Snow <ericsnowcurrently@gmail.com>
To: "Steven D'Aprano" <steve+comp.lang.python@pearwood.info>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Cc: python-list@python.org
Precedence: list
Newsgroups: comp.lang.python
Message-ID: <mailman.86.1307725303.11593.python-list@python.org>
Lines: 72
NNTP-Posting-Host: 82.94.164.166
Xref: x330-a1.tempe.blueboxinc.net comp.lang.python:7385

On Fri, Jun 10, 2011 at 10:47 AM, Steven D'Aprano
<steve+comp.lang.python@pearwood.info> wrote:
> Here's some Python 3 code that uses a factory function as a metaclass to
> inherit docstrings. Give the class a docstring of an empty string, and it
> will be inherited from the first superclass found with a non-empty
> docstring.
>
>

Yeah, the idea of an empty docstring to trigger docstring inheritance
really appeals to me.  Nice example.  Incidently, aren't metaclasses
always inherited, as opposed to class decorators (which are never)?

-eric

>
> def InheritableDocstring(name, bases, dict):
> =A0 =A0mro =3D None
> =A0 =A0docstring =3D dict.get('__doc__')
> =A0 =A0if docstring =3D=3D '':
> =A0 =A0 =A0 =A0# Search the MRO for the first non-empty docstring. We let=
 Python
> =A0 =A0 =A0 =A0# do all the hard work of calculating the MRO.
> =A0 =A0 =A0 =A0mro =3D type('K', bases, {}).__mro__[1:] =A0# Exclude the =
class K.
> =A0 =A0 =A0 =A0# Also exclude object.
> =A0 =A0 =A0 =A0assert mro[-1] =3D=3D object
> =A0 =A0 =A0 =A0mro =3D mro[:-1]
> =A0 =A0 =A0 =A0for cls in mro:
> =A0 =A0 =A0 =A0 =A0 =A0if cls.__doc__:
> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0docstring =3D cls.__doc__
> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0break
> =A0 =A0 =A0 =A0else:
> =A0 =A0 =A0 =A0 =A0 =A0docstring =3D None
> =A0 =A0 =A0 =A0dict['__doc__'] =3D docstring
> =A0 =A0assert dict.get('__doc__') !=3D ''
> =A0 =A0# Create the class we want, and return it.
> =A0 =A0cls =3D type(name, bases, dict)
> =A0 =A0if mro:
> =A0 =A0 =A0 =A0assert cls.__mro__ =3D=3D (cls,) + mro + (object,)
> =A0 =A0return cls
>
>
>
> class A(metaclass=3DInheritableDocstring):
> =A0 =A0pass
>
> class B(A, metaclass=3DInheritableDocstring):
> =A0 =A0''
>
> class C(B, metaclass=3DInheritableDocstring):
> =A0 =A0'A docstring.'
>
> class D(B, metaclass=3DInheritableDocstring):
> =A0 =A0pass
>
> class E(D, C, metaclass=3DInheritableDocstring):
> =A0 =A0''
>
> class F(E, metaclass=3DInheritableDocstring):
> =A0 =A0''
>
> assert all(cls.__doc__ is None for cls in (A, B, D))
> assert all(cls.__doc__ =3D=3D 'A docstring.' for cls in (C, E, F))
>
>
>
> --
> Steven
> --
> http://mail.python.org/mailman/listinfo/python-list
>