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

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

Re: how to inherit docstrings?

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

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: how to inherit docstrings? Ethan Furman <ethan@stoneleaf.us> - 2011-06-09 09:10 -0700
    Re: how to inherit docstrings? Gregory Ewing <greg.ewing@canterbury.ac.nz> - 2011-06-10 10:27 +1200
      Re: how to inherit docstrings? Eric Snow <ericsnowcurrently@gmail.com> - 2011-06-09 17:16 -0600
      Re: how to inherit docstrings? Ben Finney <ben+python@benfinney.id.au> - 2011-06-10 09:23 +1000
        Re: how to inherit docstrings? Eric Snow <ericsnowcurrently@gmail.com> - 2011-06-09 17:31 -0600

#7304 — Re: how to inherit docstrings?

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~

[toc] | [next] | [standalone]

#7324

IMO, it shouldn't be necessary to explicitly copy docstrings
around like this in the first place. Either it should happen
automatically, or help() should be smart enough to look up
the inheritance hierarchy when given a method that doesn't
have a docstring of its own.

Unfortunately, since unbound methods were ditched,
help(Foo.blarg) no longer has an easy way to find the base
classes, so help from the compiler may be needed.

-- 
Greg

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

#7328

On Thu, Jun 9, 2011 at 4:27 PM, Gregory Ewing
<greg.ewing@canterbury.ac.nz> wrote:
> IMO, it shouldn't be necessary to explicitly copy docstrings
> around like this in the first place. Either it should happen
> automatically, or help() should be smart enough to look up
> the inheritance hierarchy when given a method that doesn't
> have a docstring of its own.
>

Auto inheriting docstrings would be nice, in some cases.  WRT help(),
keep in mind that docstrings are used for a bunch of other things,
like doctests and some DSLs.

-eric

> Unfortunately, since unbound methods were ditched,
> help(Foo.blarg) no longer has an easy way to find the base
> classes, so help from the compiler may be needed.
>
> --
> Greg
> --
> http://mail.python.org/mailman/listinfo/python-list
>

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

#7330

Gregory Ewing <greg.ewing@canterbury.ac.nz> writes:

> IMO, it shouldn't be necessary to explicitly copy docstrings around
> like this in the first place. Either it should happen automatically,
> or help() should be smart enough to look up the inheritance hierarchy
> when given a method that doesn't have a docstring of its own.

Since the docstrings are useful in more places than just ‘help’, I'm +1
on having docstrings be automatically inherited if not specified.

Would the OP like to propose this on ‘python-ideas’?

-- 
 \        “Odious ideas are not entitled to hide from criticism behind |
  `\          the human shield of their believers' feelings.” —Richard |
_o__)                                                         Stallman |
Ben Finney

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

#7332

On Thu, Jun 9, 2011 at 5:23 PM, Ben Finney <ben+python@benfinney.id.au> wrote:
> Gregory Ewing <greg.ewing@canterbury.ac.nz> writes:
>
>> IMO, it shouldn't be necessary to explicitly copy docstrings around
>> like this in the first place. Either it should happen automatically,
>> or help() should be smart enough to look up the inheritance hierarchy
>> when given a method that doesn't have a docstring of its own.
>
> Since the docstrings are useful in more places than just ‘help’, I'm +1
> on having docstrings be automatically inherited if not specified.
>
> Would the OP like to propose this on ‘python-ideas’?
>

Yeah, I'll do that.  Thanks.

-eric

> --
>  \        “Odious ideas are not entitled to hide from criticism behind |
>  `\          the human shield of their believers' feelings.” —Richard |
> _o__)                                                         Stallman |
> Ben Finney
> --
> http://mail.python.org/mailman/listinfo/python-list
>

[toc] | [prev] | [standalone]

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

csiph-web