how to inherit docstrings?

[Tim Chase]

On 06/09/2011 01:22 AM, Eric Snow wrote:
> 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.  You can do this with decorators (after the class
> definition), with class decorators, and with metaclasses [1].

While asking for __doc__ ponies and picking colors for 
bike-sheds, in a similar vein, I've occasionally wanted to do 
something like

   class Foo:
     @property
     def __doc__(self):
       return dynamically_generated_string
       # perhaps using introspection

This would have been most helpful in things like generating help 
(like in command-line parsers), where the doc-string can 
introspect the class and learn about its methods at runtime. 
Some things seem to inherit, some don't, and help() doesn't seem 
to pick up on any of the dynamically-defined __doc__ properties. 
  Test code below.

-tkc



from datetime import datetime
from sys import stdout
class Base(object):
   "Base docstring"
   @property
   def __doc__(self):
     return datetime.now().strftime('%c')

class WithDoc(Base):
   "WithDoc docstring"
   pass

class WithoutDoc(Base): pass

base = Base()
has = WithDoc()
lacks = WithoutDoc()

for test in (
   "help(base)", # why not in help?
   "help(has)", # expected
   "help(lacks)", # why not in help?
   "help(Base)",
   "help(WithDoc)", # expected
   "help(WithoutDoc)",
   "stdout.write(repr(base.__doc__))", # works
   "stdout.write(repr(has.__doc__))", # expected
   "stdout.write(repr(lacks.__doc__))", # where'd it go?
   "stdout.write(repr(Base.__doc__))", # expected
   "stdout.write(repr(WithDoc.__doc__))", # expected
   "stdout.write(repr(WithoutDoc.__doc__))", # what?
   ):
   print test
   eval(test)
   print