[Patches] [ python-Patches-550290 ] __doc__ strings of builtin types

noreply@sourceforge.net noreply@sourceforge.net
Tue, 07 May 2002 10:06:25 -0700


Patches item #550290, was opened at 2002-04-29 19:58
You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=305470&aid=550290&group_id=5470

Category: None
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Thomas Heller (theller)
Assigned to: Nobody/Anonymous (nobody)
Summary: __doc__ strings of builtin types

Initial Comment:
pydoc creates a strange description for the __doc__
member: it prints the doc-string of 'str'. Example:


C:\>c:\sf\python\dist\src\PCBuild\python.exe
Python 2.3a0 (#29, Apr 15 2002, 18:33:31) [MSC 32 bit
(Intel)] on win32
Type "help", "copyright", "credits" or "license" for
more information.
>>> class O(object):
...   "some text"
...
>>> import pydoc
>>> pydoc.help(O)
Help on class O in module __main__:

class O(__builtin__.object)
 |  some text
 |
 |  Data and non-method functions defined here:
 |
 |  __dict__ = <dict-proxy object at 0x0080D410>
 |
 |  __doc__ = 'some text'
 |      str(object) -> string
 |
 |      Return a nice string representation of the object.
 |      If the argument is a string, the return value
is the same object.
 |

The attached patch prints the following (also for the
HTML output):
 |  __doc__ = 'some text'
 |      The documentation string
 |


----------------------------------------------------------------------

>Comment By: Thomas Heller (theller)
Date: 2002-05-07 19:06

Message:
Logged In: YES 
user_id=11105

No, I cannot think of a better wording.
The problem (as you know) is that we have to cover three 
cases: the str() function, the str type, and the string 
instances (same for all the other 'simple' types).
Would it be worth to add a _doc field to the PyStringObject 
structure and add a __doc__ entry to tp_members?

----------------------------------------------------------------------

Comment By: Guido van Rossum (gvanrossum)
Date: 2002-05-07 14:34

Message:
Logged In: YES 
user_id=6380

The instance doc is supposed to be the same as the class
doc, yes.

I suppose the str() __doc__ is not particularly appropriate
for string instances.

Can you suggest a better wording? (This problem is
widespread, I presume, so a generic solution may be in
order.)

----------------------------------------------------------------------

Comment By: Thomas Heller (theller)
Date: 2002-04-30 16:50

Message:
Logged In: YES 
user_id=11105

Please ignore my previous comments.

It turns out that the problem is not in pydoc, it is in
Python itself. "spam".__doc__ is the same as str.__doc__
(which describes what the callable 'str' does.
Is this intended?

The side-effect is that pydoc prints unexpected output for
class variables. Execute this code to find out:

class X:
    a = "a string"
    b = 42

import pydoc
pydoc.help(X)



----------------------------------------------------------------------

Comment By: Thomas Heller (theller)
Date: 2002-04-30 16:49

Message:
Logged In: YES 
user_id=11105

Please ignore my previous comments.

It turns out that the problem is not in pydoc, it is in
Python itself. "spam".__doc__ is the same as str.__doc__
(which describes what the callable 'str' does.
Is this intended?

The side-effect is that pydoc prints unexpected output for
class variables. Execute this code to find out:

class X:
    a = "a string"
    b = 42

import pydoc
pydoc.help(X)



----------------------------------------------------------------------

Comment By: Thomas Heller (theller)
Date: 2002-04-30 10:24

Message:
Logged In: YES 
user_id=11105

The same problem exists for the __module__ attribute. I can
update the patch if needed.

----------------------------------------------------------------------

You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=305470&aid=550290&group_id=5470