Issue 8488: Docstrings of non-data descriptors "ignored" (original) (raw)

Created on 2010-04-21 18:25 by torsten, last changed 2022-04-11 14:57 by admin. This issue is now closed.

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