Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #7331 > unrolled thread

__doc__ immutable for classes (was: Re: how to inherit docstrings?)

Back to article view | Back to comp.lang.python

Contents

  __doc__ immutable for classes (was: Re: how to inherit docstrings?) Eric Snow <ericsnowcurrently@gmail.com> - 2011-06-09 17:29 -0600
    Re: __doc__ immutable for classes (was: Re: how to inherit docstrings?) Gregory Ewing <greg.ewing@canterbury.ac.nz> - 2011-06-10 19:31 +1200
      Re: __doc__ immutable for classes Terry Reedy <tjreedy@udel.edu> - 2011-06-10 21:17 -0400

#7331 — __doc__ immutable for classes (was: Re: how to inherit docstrings?)

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?  I was thinking about the idea of inheriting class
>> docstrings too.
>
> 8<--------------------------------------------------------
> """module level docstring"""
>
> def func():
>    """function level docstring"""
>
> class Test(object):
>    """class level docstring"""
>    def meth(self):
>        """method level docstring"""
>
>
> if __name__ == '__main__':
>    import sys
>    import traceback
>    hmmm = (
>        sys.modules['__main__'],
>        func,
>        Test(),
>        Test().meth,
>        Test,
>        Test.meth,
>        )
>    for obj in hmmm:
>        try:
>            obj.__doc__ = 'new docstring'
>            print('successfully changed %s\n' % obj)
>        except:
>            traceback.print_exc()
>            print()
> 8<--------------------------------------------------------
>
> Tested from 2.5 - 3.2.  The 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):
>  File "docstring.py", line 25, in <module>
>    obj.__doc__ = 'new docstring'
> AttributeError: attribute '__doc__' of 'instancemethod' objects is not
> writable
> ()
> Traceback (most recent call last):
>  File "docstring.py", line 25, in <module>
>    obj.__doc__ = 'new docstring'
> AttributeError: attribute '__doc__' of 'type' objects is not writable
> ()
> Traceback (most recent call last):
>  File "docstring.py", line 25, in <module>
>    obj.__doc__ = '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):
>  File "docstring.py", line 25, in <module>
>    obj.__doc__ = 'new docstring'
> AttributeError: attribute '__doc__' of 'method' objects is not writable
>
> Traceback (most recent call last):
>  File "docstring.py", line 25, in <module>
>    obj.__doc__ = '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

[toc] | [next] | [standalone]

#7362

Eric Snow wrote:
> But for "method" objects  (really a wrapper for
> bound functions) would it change the __doc__ of the wrapper or of the
> bound function?

You probably wouldn't want to change the __doc__ of a method
wrapper; instead you'd make sure you got hold of the underlying
function first. So __doc__ on method wrappers should probably
remain read-only to avoid surprises.

-- 
Greg

[toc] | [prev] | [next] | [standalone]

#7424 — Re: __doc__ immutable for classes

On 6/10/2011 3:31 AM, Gregory Ewing wrote:
> Eric Snow wrote:
>> But for "method" objects (really a wrapper for
>> bound functions) would it change the __doc__ of the wrapper or of the
>> bound function?
>
> You probably wouldn't want to change the __doc__ of a method
> wrapper; instead you'd make sure you got hold of the underlying
> function first. So __doc__ on method wrappers should probably
> remain read-only to avoid surprises.

In 3.x there are no general method wrappers; only bound methods. The 
.__doc__ attribute of bound methods equals and I am very sure *is* the 
doc string of the underlying function, accessed through a custom 
method.__getattr__. It is not writable through the bound method. I 
presume this is because method.__setattr__ blocks the write. Directly 
binding a new string to the underlying function does work.

-- 
Terry Jan Reedy

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web