__doc__ strings of builtin types

[theller]

BPO	550290
Nosy	@gvanrossum, @theller, @rhettinger
Files	pydoc.diff: Patch for pydoc. stringobject.diff: Patch for stringobject.c pydoc2.diff: Alternative patch for pydoc

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/gvanrossum'
closed_at = <Date 2002-05-21.20:58:22.000>
created_at = <Date 2002-04-29.17:58:31.000>
labels = []
title = '__doc__ strings of builtin types'
updated_at = <Date 2002-05-21.20:58:22.000>
user = 'https://github.com/theller'

bugs.python.org fields:

activity = <Date 2002-05-21.20:58:22.000>
actor = 'gvanrossum'
assignee = 'gvanrossum'
closed = True
closed_date = None
closer = None
components = ['None']
creation = <Date 2002-04-29.17:58:31.000>
creator = 'theller'
dependencies = []
files = ['4206', '4207', '4208']
hgrepos = []
issue_num = 550290
keywords = ['patch']
message_count = 15.0
messages = ['39755', '39756', '39757', '39758', '39759', '39760', '39761', '39762', '39763', '39764', '39765', '39766', '39767', '39768', '39769']
nosy_count = 3.0
nosy_names = ['gvanrossum', 'theller', 'rhettinger']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue550290'
versions = []

[theller]

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
|

[theller]

Logged In: YES
user_id=11105

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

[theller]

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)

[theller]

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)

[gvanrossum]

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.)

[theller]

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?

[theller]

Logged In: YES
user_id=11105

Or maybe add a __doc__ tp_member (or whatever) which always
returns None?

[theller]

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.

[rhettinger]

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.

[gvanrossum]

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).

[gvanrossum]

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?

[theller]

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.

[gvanrossum]

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?

[theller]

Logged In: YES
user_id=11105

Guido, after applying pydoc2.diff I'm happy. I retract
the "feature request".

[gvanrossum]

Logged In: YES
user_id=6380

OK, I've checked in pydoc2.diff.

I'm not sure if we need to do anything about the docstrings
of basic objects; I'll close this bug report, if there's a
desire for a change there, somebody can open a new bug
report.