[issue39125] Type signature of @property not shown in help()
New submission from Nguyễn Gia Phong vn.mcsinyx@gmail.com:
Dear Maintainer,
I want to request a feature on the generative documentation of type-hinting. As of December 2019, I believe there is no support for generating such information in help(). For demonstration, I have this tiny piece of code
class Foo: @property def bar(self) -> int: return 42
@bar.setter def bar(self, value: int) -> None: pass
def baz(self, arg: float) -> str: pass
whose documentation on CPython 3.7.5 (on Debian testing amd64 if that matters) is generated as
class Foo(builtins.object) | Methods defined here: | | baz(self, arg: float) -> str | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if defined) | | __weakref__ | list of weak references to the object (if defined) | | bar
I expect the documentation for bar to be as informative as bar, i.e. something similar to ``bar: int''. As pointed out by ChrisWarrick on freenode#python, the annotations are already present, yet help() is not making use of them:
Foo.bar.fget.__annotations__
{'return': <class 'int'>}
Foo.bar.fset.__annotations__
{'value': <class 'int'>, 'return': None}
Have a Merry Christmas or other holiday of your choice, Nguyễn Gia Phong
---------- assignee: docs@python components: Documentation messages: 358823 nosy: McSinyx, docs@python priority: normal severity: normal status: open title: Type signature of @property not shown in help() type: enhancement versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue39125 _______________________________________
Karthikeyan Singaravelan tir.karthi@gmail.com added the comment:
Currently docstring written for even property.setter is ignored in help as inspect.getdoc only inspects property.fget [0] for docstrings. I feel docs for setter could also be included. The docs also indicate the same at https://docs.python.org/3.6/library/functions.html#property . In the absence of docs maybe the signature for getter and setter could be included as per this proposal.
class Foo: @property def bar(self) -> int: '''Bar docs for property''' return 42
@bar.setter def bar(self, value: int) -> None: '''Bar docs for setter''' pass
help(Foo.bar)
Help on property:
Bar docs for property
[0] https://github.com/python/cpython/blob/4b3b1226e86df6cd45e921c8f2ad23c3639c4...
---------- nosy: +rhettinger, xtreak versions: -Python 3.5, Python 3.6, Python 3.7, Python 3.8
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue39125 _______________________________________
Nguyễn Gia Phong vn.mcsinyx@gmail.com added the comment:
Relating to this, should there also be indication about the mode (get, set, del) the property? Currently there is no way to tell if the *attribute* is read-only, read-write or write-only.
---------- versions: -Python 3.9
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue39125 _______________________________________
Change by Nguyễn Gia Phong vn.mcsinyx@gmail.com:
---------- versions: +Python 3.9
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue39125 _______________________________________
brenthuisman brent@huisman.pl added the comment:
Is there any activity on this issue? The way Pybind11 generates accessors for attributes makes (as properties with getter and setter) makes it currently impossible to view the type info, which Pybind does provide.
Thanks for any update.
---------- nosy: +brenthuisman
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue39125 _______________________________________
Raymond Hettinger raymond.hettinger@gmail.com added the comment:
Currently there is no way to tell if the *attribute* is read-only, read-write or write-only.
Read-only is segregated in the help() output.
class A:
@property def computed_field(self): 'An example property'
help(A)
Help on class A in module __main__:
class A(builtins.object) | Readonly properties defined here: | | computed_field | An example property | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if defined) | | __weakref__
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue39125 _______________________________________
participants (4)
-
brenthuisman -
Karthikeyan Singaravelan
-
Nguyễn Gia Phong
-
Raymond Hettinger