[Patches] [ python-Patches-550290 ] __doc__ strings of builtin types
noreply@sourceforge.net
noreply@sourceforge.net
Tue, 21 May 2002 12:39:55 -0700
Patches item #550290, was opened at 2002-04-29 13: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: Guido van Rossum (gvanrossum)
Date: 2002-05-21 15:39
Message:
Logged In: YES
user_id=6380
> Hm, I see no pydoc2.diff ;-)
Oops, here's pydoc2.diff
> IMO, pydoc should try to document the _purpose_ of the
> special attributes (__doc__, __module__, ...) instead
> of their _value_.
Maybe, but aren't there lots of these? Maybe this ought to
be table-driven instead of an if-statement for each one.
I'll call YAGNI on this one for now; at best it's a separate
feature request.
> > For the other issue, I'm not sure *what* to do. Tim
suggests
> > that perhaps for the basic types, x.__doc__ should
return
> > None. Opinions?
> That's what my sample patch stringobject.diff does.
> +1 from me.
That's what I realized after looking at your string patch.
:-)
Raymond, do you want to work on finishing this?
----------------------------------------------------------------------
Comment By: Thomas Heller (theller)
Date: 2002-05-21 15:24
Message:
Logged In: YES
user_id=11105
> I think there are actually two issues here: pydoc shows the
> docstrings for what it calls "data and non-method
> functions", which usually aren't helpful; and the docstrings
> for basic types are confusing when retrieved through an
> instance.
>
> For the pydoc issue, I have a different patch
> (pydoc2.diff). This suppresses the docstring completely
> unless the value is callable. (Now, I know that callable()
> is not 100% reliable, but it's close enough for pydoc.)
Hm, I see no pydoc2.diff ;-)
IMO, pydoc should try to document the _purpose_ of the
special attributes (__doc__, __module__, ...) instead
of their _value_.
> For the other issue, I'm not sure *what* to do. Tim suggests
> that perhaps for the basic types, x.__doc__ should return
> None. Opinions?
That's what my sample patch stringobject.diff does.
+1 from me.
----------------------------------------------------------------------
Comment By: Guido van Rossum (gvanrossum)
Date: 2002-05-21 15:13
Message:
Logged In: YES
user_id=6380
I think there are actually two issues here: pydoc shows the
docstrings for what it calls "data and non-method
functions", which usually aren't helpful; and the docstrings
for basic types are confusing when retrieved through an
instance.
For the pydoc issue, I have a different patch
(pydoc2.diff). This suppresses the docstring completely
unless the value is callable. (Now, I know that callable()
is not 100% reliable, but it's close enough for pydoc.)
For the other issue, I'm not sure *what* to do. Tim suggests
that perhaps for the basic types, x.__doc__ should return
None. Opinions?
----------------------------------------------------------------------
Comment By: Guido van Rossum (gvanrossum)
Date: 2002-05-16 08:36
Message:
Logged In: YES
user_id=6380
I'm very sympathetic, but have no time to review this just
yet. Please don't check in without my approval -- this is
awfully deep shit (see the history of the __doc__ descriptor
in typeobject.c).
----------------------------------------------------------------------
Comment By: Raymond Hettinger (rhettinger)
Date: 2002-05-15 11:13
Message:
Logged In: YES
user_id=80475
Since this would also go into int, float, and other places,
consider factoring it to abstract.c as
PyObject_GenericGetNoneDoc or some such.
----------------------------------------------------------------------
Comment By: Thomas Heller (theller)
Date: 2002-05-15 08:51
Message:
Logged In: YES
user_id=11105
The attatched patch (stringobject.diff) implements this
behaviour: The doc string of 'str' is unchanged, but string
objects have a __doc__ attribute of None.
The same could (and should) be done for int, float, and
probably more types as well.
----------------------------------------------------------------------
Comment By: Thomas Heller (theller)
Date: 2002-05-07 13:08
Message:
Logged In: YES
user_id=11105
Or maybe add a __doc__ tp_member (or whatever) which always
returns None?
----------------------------------------------------------------------
Comment By: Thomas Heller (theller)
Date: 2002-05-07 13: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 08: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 10: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 10: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 04: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