[Python-ideas] inheriting docstrings and mutable docstings for classes

[Eric Snow]

I noticed that __doc__ for classes is immutable:

>>> class X:
...     "some doc"
...
>>> X.__doc__
'some doc'
>>> X.__doc__ = "another doc"
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
AttributeError: attribute '__doc__' of 'type' objects is not writable

That is on 3.3, but apparently it's the case all the way back to 2.2.
I mentioned this on python-list and several people indicated that it
should be an unnecessary restriction [1].  Someone else pointed out
that docstrings also behave this way for method objects [2].

I want too see if it would be okay to make __doc__ writable for
classes.  I am not sure about for method objects, since I've never
thought to do that, but it is analogous to class instances, where
__doc__ is mutable and distinct from the class docstring.  I just
don't have any use cases that would dictate changing the docstring of
the method object, the wrapped function, or neither when changing
__doc__.

Someone else on the thread indicated that perhaps docstrings should be
inherited and got some support [3][4].  It makes sense to me for many,
but not necessarily all, cases.  However, if you don't want to inherit
you can simply set an empty docstring.  Docstrings impact help(),
doctests, and some DSLs.  I'm +1 on having __doc__ be inherited.

Thanks,

-eric


[1] http://mail.python.org/pipermail/python-list/2011-June/1274079.html
[2] http://mail.python.org/pipermail/python-list/2011-June/1274080.html
[3] http://mail.python.org/pipermail/python-list/2011-June/1274099.html
[4] http://mail.python.org/pipermail/python-list/2011-June/1274105.html