[New-bugs-announce] [issue36401] Readonly properties should be marked as such in help()

[Raymond Hettinger]

New submission from Raymond Hettinger <raymond.hettinger at gmail.com>:

It is common to create read-only properties with the '@property' decoration but the existing help() output doesn't annotate them as such.

One way to go is to annotate each one separately:

 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from _IPAddressBase:
 |  
 |  compressed (read-only property)             <== NEW ANNOTATION
 |      Return the shorthand version of the IP address as a string.
 |  
 |  exploded (read-only property)               <== NEW ANNOTATION
 |      Return the longhand version of the IP address as a string.
 |  
 |  reverse_pointer (read-only property)        <== NEW ANNOTATION
 |      The name of the reverse DNS pointer for the IP address, e.g.:
 |      >>> ipaddress.ip_address("127.0.0.1").reverse_pointer
 |      '1.0.0.127.in-addr.arpa'
 |      >>> ipaddress.ip_address("2001:db8::1").reverse_pointer
 |      '1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa'


Another way to go is to break the data descriptor section into two sections --- isolate those that define __set__ or __delete__ from those that don't.

For example, given this code:

    class A:
        'Variety of descriptors and method'

        __slots__ = '_w', '_x'

        def __init__(self, w: int, x: str):
            'initializer'
            self.w = w
            self.x = x

        @classmethod
        def cm(cls, u):
            'do something with u'
            return cls(u * 4)

        @staticmethod
        def sm(v):
            'do something with v'
            return v * 3

        @property
        def rop(self):
            'computed field'
            return self._w * 2

        @property
        def wandr(self):
            'managed attribute'
            return self._w

        @wandr.setter
        def wandr(self, w):
            self._w = w


Produce this help output:

Help on class A in module __main__:

    class A(builtins.object)
     |  A(w: int, x: str)
     |  
     |  Variety of descriptors and method
     |  
     |  Methods defined here:
     |  
     |  __init__(self, w: int, x: str)
     |      initializer
     |  
     |  ----------------------------------------------------------------------
     |  Class methods defined here:
     |  
     |  cm(u) from builtins.type
     |      do something with u
     |  
     |  ----------------------------------------------------------------------
     |  Static methods defined here:
     |  
     |  sm(v)
     |      do something with v
     |  
     |  ----------------------------------------------------------------------
     |  Read-only descriptors defined here:        <== NEW HEADING
     |  
     |  rop
     |      computed field
     |  
     |  ----------------------------------------------------------------------
     |  Mutable data descriptors defined here:     <== NEW HEADING AND SECTION    
     |  
     |  wandr
     |      managed attribute

----------
components: Library (Lib)
messages: 338621
nosy: rhettinger
priority: normal
severity: normal
status: open
title: Readonly properties should be marked as such in help()
type: enhancement
versions: Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue36401>
_______________________________________