classification
Title: Docstrings of non-data descriptors "ignored"
Type: behavior Stage:
Components: Library (Lib) Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: benjamin.peterson, merwok, r.david.murray, serhiy.storchaka, torsten, yselivanov
Priority: low Keywords:

Created on 2010-04-21 18:25 by torsten, last changed 2017-03-26 13:36 by serhiy.storchaka.

Files
File name Uploaded Description Edit
doc.py torsten, 2010-04-21 18:25 Example code showing the issue
Messages (5)
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()?
History
Date User Action Args
2017-03-26 13:36:01serhiy.storchakasetnosy: + serhiy.storchaka, yselivanov
messages: + msg290527
2011-06-09 16:12:09merwoksetnosy: + merwok

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