classification
Title: Type signature of @property not shown in help()
Type: enhancement Stage:
Components: Documentation Versions: Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: McSinyx, brenthuisman, docs@python, rhettinger, xtreak
Priority: normal Keywords:

Created on 2019-12-23 15:40 by McSinyx, last changed 2021-04-11 00:19 by rhettinger.

Messages (5)
msg358823 - (view) Author: Nguyễn Gia Phong (McSinyx) Date: 2019-12-23 15:40
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
msg358825 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python committer) Date: 2019-12-23 16:37
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/4b3b1226e86df6cd45e921c8f2ad23c3639c43b2/Lib/inspect.py#L580
msg359041 - (view) Author: Nguyễn Gia Phong (McSinyx) Date: 2019-12-30 14:02
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.
msg390625 - (view) Author: (brenthuisman) Date: 2021-04-09 13:50
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.
msg390754 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-04-11 00:19
> 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__
History
Date User Action Args
2021-04-11 00:19:47rhettingersetmessages: + msg390754
2021-04-09 13:50:12brenthuismansetnosy: + brenthuisman
messages: + msg390625
2020-01-02 12:13:42McSinyxsetversions: + Python 3.9
2019-12-30 14:02:44McSinyxsetmessages: + msg359041
versions: - Python 3.9
2019-12-23 16:37:13xtreaksetnosy: + rhettinger, xtreak

messages: + msg358825
versions: - Python 3.5, Python 3.6, Python 3.7, Python 3.8
2019-12-23 15:40:00McSinyxcreate