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

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.

FYI, this still applies to r86094 of py3k.

pydoc should probably be adapted to look at a type for descrs.

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()?

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)

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.

Ah yes. 

Bisect seems to be pointing at this commit: https://github.com/python/cpython/commit/fbf2786c4c89430e2067016603078cf3500cfe94

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.

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.