how to inherit docstrings?

[Ian Kelly]

On Fri, Jun 10, 2011 at 10:55 AM, Eric Snow <ericsnowcurrently at gmail.com> wrote:
> 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.

Everybody always focuses so much on properties and forgets that you
can also just write your own descriptors.

>>> 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