how to inherit docstrings?

[Eric Snow]

On Fri, Jun 10, 2011 at 11:26 AM, Ian Kelly <ian.g.kelly at gmail.com> wrote:
> Everybody always focuses so much on properties and forgets that you
> can also just write your own descriptors.
>

I'm so glad that you pointed this out.  I totally forgot that
properties simply returned themselves if not called on the instance.
You are right about a custom descriptor.

-eric

>>>> class DocDescriptor(object):
> ...   def __get__(self, instance, owner):
> ...     return getattr(owner, "_mydoc", None)
> ...
>>>> class Meta(type):
> ...   def __init__(cls, name, bases, d):
> ...     super(Meta, cls).__init__(name, bases, d)
> ...     cls.__doc__ = DocDescriptor()
> ...
>>>> class X(object):
> ...   __metaclass__ = Meta
> ...
>>>> X.__doc__
>>>> X().__doc__
>>>> X._mydoc = 'test'
>>>> X.__doc__
> 'test'
>>>> X().__doc__
> 'test'
>>>> class Derived(X): pass
> ...
>>>> Derived.__doc__
> 'test'
>>>> Derived().__doc__
> 'test'
>
> There you go, a metaclass that adds a __doc__ descriptor that can be
> inherited (thanks to the metaclass), can be accessed from either the
> class or the instance (thanks to the descriptor), and can easily be
> modified to generate the doc string dynamically at call-time if
> desired.
>
> Cheers,
> Ian
>