Path: csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!aioe.org!feeder.news-service.com!newsfeed.xs4all.nl!newsfeed6.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:date:message-id:subject:from:to:cc:content-type :content-transfer-encoding; b=a0U/EreVXpc0C/jDI6zlwmrk+h9GhH8SZ4j+A0uKBpC5urOz7VGN+pwRXrxwxU8JKs qi071u5b7Iwhehz5BQjbtEYCXsSKnlYD6Yp9PlVTnBauae5suvmmJ5EuUR0ylHrXdHI/ yCNiyUp9YxSajZoPqTRlujireXcL250OxXEv4=
MIME-Version: 1.0
Date: Thu, 9 Jun 2011 17:29:35 -0600
Subject: __doc__ immutable for classes (was: Re: how to inherit docstrings?)
From: Eric Snow <ericsnowcurrently@gmail.com>
To: Ethan Furman <ethan@stoneleaf.us>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Cc: python-list <python-list@python.org>
Precedence: list
Newsgroups: comp.lang.python
Message-ID: <mailman.65.1307662177.11593.python-list@python.org>
Lines: 101
NNTP-Posting-Host: 82.94.164.166
Xref: x330-a1.tempe.blueboxinc.net comp.lang.python:7331

On Thu, Jun 9, 2011 at 10:10 AM, Ethan Furman <ethan@stoneleaf.us> wrote:
> Eric Snow wrote:
>>
>> p.s. Am I missing something or can you really not change the docstring
>> of a class? =A0I was thinking about the idea of inheriting class
>> docstrings too.
>
> 8<--------------------------------------------------------
> """module level docstring"""
>
> def func():
> =A0 =A0"""function level docstring"""
>
> class Test(object):
> =A0 =A0"""class level docstring"""
> =A0 =A0def meth(self):
> =A0 =A0 =A0 =A0"""method level docstring"""
>
>
> if __name__ =3D=3D '__main__':
> =A0 =A0import sys
> =A0 =A0import traceback
> =A0 =A0hmmm =3D (
> =A0 =A0 =A0 =A0sys.modules['__main__'],
> =A0 =A0 =A0 =A0func,
> =A0 =A0 =A0 =A0Test(),
> =A0 =A0 =A0 =A0Test().meth,
> =A0 =A0 =A0 =A0Test,
> =A0 =A0 =A0 =A0Test.meth,
> =A0 =A0 =A0 =A0)
> =A0 =A0for obj in hmmm:
> =A0 =A0 =A0 =A0try:
> =A0 =A0 =A0 =A0 =A0 =A0obj.__doc__ =3D 'new docstring'
> =A0 =A0 =A0 =A0 =A0 =A0print('successfully changed %s\n' % obj)
> =A0 =A0 =A0 =A0except:
> =A0 =A0 =A0 =A0 =A0 =A0traceback.print_exc()
> =A0 =A0 =A0 =A0 =A0 =A0print()
> 8<--------------------------------------------------------
>
> Tested from 2.5 - 3.2. =A0The first three always work, the last one works=
 in
> 3.1+, the fourth and fifth always fail.
>
> -----------------actual output for 2.5--------------------
> successfully changed <module '__main__' from 'docstring.py'>
>
> successfully changed <function func at 0x00A8F570>
>
> successfully changed <__main__.Test object at 0x00A94230>
>
> Traceback (most recent call last):
> =A0File "docstring.py", line 25, in <module>
> =A0 =A0obj.__doc__ =3D 'new docstring'
> AttributeError: attribute '__doc__' of 'instancemethod' objects is not
> writable
> ()
> Traceback (most recent call last):
> =A0File "docstring.py", line 25, in <module>
> =A0 =A0obj.__doc__ =3D 'new docstring'
> AttributeError: attribute '__doc__' of 'type' objects is not writable
> ()
> Traceback (most recent call last):
> =A0File "docstring.py", line 25, in <module>
> =A0 =A0obj.__doc__ =3D 'new docstring'
> AttributeError: attribute '__doc__' of 'instancemethod' objects is not
> writable
> ()
> -----------------actual output for 3.2--------------------
> successfully changed <module '__main__' from 'docstring.py'>
>
> successfully changed <function func at 0x00BE6F60>
>
> successfully changed <__main__.Test object at 0x00BFE730>
>
> Traceback (most recent call last):
> =A0File "docstring.py", line 25, in <module>
> =A0 =A0obj.__doc__ =3D 'new docstring'
> AttributeError: attribute '__doc__' of 'method' objects is not writable
>
> Traceback (most recent call last):
> =A0File "docstring.py", line 25, in <module>
> =A0 =A0obj.__doc__ =3D 'new docstring'
> AttributeError: attribute '__doc__' of 'type' objects is not writable
>
> successfully changed <function meth at 0x00BE6ED0>
> -----------------actual output----------------------------
>
> ~Ethan~
>

Thanks for looking up all of that, Ethan!  I would love to see __doc__
writable for classes.  But for "method" objects  (really a wrapper for
bound functions) would it change the __doc__ of the wrapper or of the
bound function?  Seems like it is analogous to the Test().__doc__
case, so the wrapper would be updated.  However, I haven't really had
a need to do that before, so I don't know which makes more sense.

Should I take this to python-ideas?  And maybe Greg's thought of auto
inheriting __doc__?

-eric