classification
Title: Docstrings of non-data descriptors "ignored"
Type: behavior Stage: resolved
Components: Library (Lib) Versions: Python 3.10, Python 3.9
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: Nosy List: benjamin.peterson, eric.araujo, iritkatriel, r.david.murray, serhiy.storchaka, sir-sigurd, torsten, yselivanov
Priority: low Keywords:

Created on 2010-04-21 18:25 by torsten, last changed 2020-11-07 22:27 by serhiy.storchaka. This issue is now closed.

Files
File name Uploaded Description Edit
doc.py torsten, 2010-04-21 18:25 Example code showing the issue
Messages (10)
msg103880 - (view) Author: Torsten Landschoff (torsten) * Date: 2010-04-21 18:25
[I would assign priority minor to this, but the tracker won't let me]

I really like the online documentation features of python. However, I wonder about the output of the following simple example:

class Descriptor(object):
    """Doc of a non-data descriptor."""
    def __get__(self, instance, owner):
        return 42 if instance else self

class GetSetDescriptor(Descriptor):
    """Doc of a data-descriptor."""
    def __set__(self, instance, value):
        pass

class Demo(object):
    non_data = Descriptor()
    data = GetSetDescriptor()

help(Demo)


This results in

Help on class Demo in module __main__:

class Demo(builtins.object)
 |  Methods defined here:
 |  
 |  non_data = <__main__.Descriptor object>
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)
 |  
 |  data
 |      Doc of a data-descriptor.


I think the behaviour of pydoc wrt. the non_data descriptor is a bit out of line. I would have expected to find the docstring in the output here.
msg103898 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-04-21 19:45
There is either an issue or a python-dev (or maybe even python-ideas) discussion about this subject somewhere.  It's a much deeper issue than it appears on the surface.
msg120254 - (view) Author: Torsten Landschoff (torsten) * Date: 2010-11-02 20:02
FYI, this still applies to r86094 of py3k.
msg120259 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2010-11-02 21:26
pydoc should probably be adapted to look at a type for descrs.
msg290527 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-03-26 13:36
Since the descriptor is classified as a routine (inspect.isroutine() returns True because inspect.ismethoddescriptor() returns True), pydoc outputs it in the "Methods defined here" section and uses the docroutine(). But docroutine() requires the __name__ attribute for determining whether this is an original method or an alias. That descriptor doesn't have the __name__ attribute. Actually it is even not callable, so it is questionable whether it can be classified as a method.

I don't know on what level this should be fixed. docroutine()? classify_class_attrs()? isroutine()? ismethoddescriptor()?
msg380465 - (view) Author: Irit Katriel (iritkatriel) * (Python triager) Date: 2020-11-06 18:34
I got this output on 3.10, so I think this has been fixed:


lass Demo(builtins.object)
 |  Readonly properties defined here:
 |
 |  data
 |
 |  non_data
 |
 |  prop
 |      Doc of a property.
 |
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables (if defined)
 |
 |  __weakref__
 |      list of weak references to the object (if defined)
msg380481 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-11-06 23:04
Python 3.7 (2.7 looks almost the same):

class Demo(builtins.object)
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)
 |  
 |  data
 |      Doc of a data-descriptor.
 |  
 |  non_data
 |      Doc of a non-data descriptor.
 |  
 |  prop
 |      Doc of a property.

Python 3.8:

class Demo(builtins.object)
 |  Readonly properties defined here:
 |  
 |  data
 |      Doc of a data-descriptor.
 |  
 |  non_data
 |      Doc of a non-data descriptor.
 |  
 |  prop
 |      Doc of a property.
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)

Python 3.9:

class Demo(builtins.object)
 |  Readonly properties defined here:
 |  
 |  data
 |  
 |  non_data
 |  
 |  prop
 |      Doc of a property.
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)

Seems the original bug was fixed, but a regression was introduced in 3.9.
msg380482 - (view) Author: Irit Katriel (iritkatriel) * (Python triager) Date: 2020-11-07 00:08
Ah yes. 

Bisect seems to be pointing at this commit: https://github.com/python/cpython/commit/fbf2786c4c89430e2067016603078cf3500cfe94
msg380526 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-11-07 22:17
Actually there is no bug in not showing docstring for "data" and "non_data". "Doc of a data-descriptor." is the docstring of the type of the descriptor, not the descriptor itself. If it would be "Type of a data-descriptor." it would be more obvious. To output the docstring for descriptor you need to set the __doc__ attribute of the instance.

The original bug is fixed. The non data descriptor is now shown in the correct section. If it would have own docstring it would be shown.

But the data descriptor is shown in wrong section. It is not readonly.
msg380528 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-11-07 22:27
Ah, all correct. In doc.py unlike to the inlined code Descriptor is a subclass of property. And since fset is None the instance is classified as a readonly property.
History
Date User Action Args
2020-11-07 22:27:09serhiy.storchakasetstatus: open -> closed
resolution: out of date
messages: + msg380528

stage: resolved
2020-11-07 22:17:37serhiy.storchakasetmessages: + msg380526
2020-11-07 00:08:15iritkatrielsetmessages: + msg380482
2020-11-06 23:04:29serhiy.storchakasetstatus: pending -> open

messages: + msg380481
versions: + Python 3.9, Python 3.10, - Python 2.7, Python 3.2, Python 3.3
2020-11-06 18:34:48iritkatrielsetstatus: open -> pending
nosy: + iritkatriel
messages: + msg380465

2018-06-14 17:48:44sir-sigurdsetnosy: + sir-sigurd
2017-03-26 13:36:01serhiy.storchakasetnosy: + serhiy.storchaka, yselivanov
messages: + msg290527
2011-06-09 16:12:09eric.araujosetnosy: + eric.araujo

versions: + Python 2.7, Python 3.3
2010-11-02 21:26:39benjamin.petersonsetnosy: + benjamin.peterson
messages: + msg120259
2010-11-02 20:55:45rhettingersetpriority: normal -> low
2010-11-02 20:02:49torstensetmessages: + msg120254
2010-04-21 19:45:13r.david.murraysetnosy: + r.david.murray

messages: + msg103898
versions: - Python 2.6, Python 2.5, Python 3.1
2010-04-21 18:25:07torstencreate