Type signature of @property not shown in help()

[McSinyx]

BPO	39125
Nosy	@rhettinger, @McSinyx, @tirkarthi

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-12-23.15:40:00.651>
labels = ['type-feature', '3.9', 'docs']
title = 'Type signature of @property not shown in help()'
updated_at = <Date 2021-04-11.00:19:47.157>
user = 'https://github.com/McSinyx'

bugs.python.org fields:

activity = <Date 2021-04-11.00:19:47.157>
actor = 'rhettinger'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-12-23.15:40:00.651>
creator = 'McSinyx'
dependencies = []
files = []
hgrepos = []
issue_num = 39125
keywords = []
message_count = 5.0
messages = ['358823', '358825', '359041', '390625', '390754']
nosy_count = 5.0
nosy_names = ['rhettinger', 'docs@python', 'McSinyx', 'xtreak', 'brenthuisman']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue39125'
versions = ['Python 3.9']

[McSinyx]

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

[tirkarthi]

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]

cpython/Lib/inspect.py

Line 580 in 4b3b122

elif isinstance(obj, property):

[McSinyx]

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.

[brenthuisman]

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.

[rhettinger]

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__