how to inherit docstrings?

[Eric Snow]

On Fri, Jun 10, 2011 at 10:47 AM, Steven D'Aprano
<steve+comp.lang.python at 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):
>    mro = None
>    docstring = dict.get('__doc__')
>    if docstring == '':
>        # Search the MRO for the first non-empty docstring. We let Python
>        # do all the hard work of calculating the MRO.
>        mro = type('K', bases, {}).__mro__[1:]  # Exclude the class K.
>        # Also exclude object.
>        assert mro[-1] == object
>        mro = mro[:-1]
>        for cls in mro:
>            if cls.__doc__:
>                docstring = cls.__doc__
>                break
>        else:
>            docstring = None
>        dict['__doc__'] = docstring
>    assert dict.get('__doc__') != ''
>    # Create the class we want, and return it.
>    cls = type(name, bases, dict)
>    if mro:
>        assert cls.__mro__ == (cls,) + mro + (object,)
>    return cls
>
>
>
> class A(metaclass=InheritableDocstring):
>    pass
>
> class B(A, metaclass=InheritableDocstring):
>    ''
>
> class C(B, metaclass=InheritableDocstring):
>    'A docstring.'
>
> class D(B, metaclass=InheritableDocstring):
>    pass
>
> class E(D, C, metaclass=InheritableDocstring):
>    ''
>
> class F(E, metaclass=InheritableDocstring):
>    ''
>
> assert all(cls.__doc__ is None for cls in (A, B, D))
> assert all(cls.__doc__ == 'A docstring.' for cls in (C, E, F))
>
>
>
> --
> Steven
> --
> http://mail.python.org/mailman/listinfo/python-list
>