Issue 36401: Readonly properties should be marked as such in help()

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

For property objects, we have to look at *fset* and *fdel* to find-out whether they are assignable:

    >>> A.rop.fset is None
    True
    >>> A.wandr.fset is None
    False

@Raymond

+1 

but can we do the same thing with the PyGetSetDef declaration for the C Part?

> but can we do the same thing with the PyGetSetDef declaration 
> for the C Part?

The would likely take an API change.  For now, using only what is already exposed in Python, we can only partition data descriptors in two groups:

* Known to be readonly because __set__ is missing or fset is None
* Possibly writeable, can't really tell until __set__ is called

Example in the latter category,  

    >>> t = time.localtime()
    >>> hasattr(type(t).tm_sec, '__set__')
    True
    >>> t.tm_sec = 31
    Traceback (most recent call last):
      File "<pyshell#23>", line 1, in <module>
         t.tm_sec = 31
    AttributeError: readonly attribute

New changeset 62be33870e2f8517314bf9c7275548e799296f7e by Raymond Hettinger in branch 'master':
bpo-36401: Have help() show readonly properties separately (GH-12517)
https://github.com/python/cpython/commit/62be33870e2f8517314bf9c7275548e799296f7e

Hi Raymond,

About the C API, I wanted to know that because I started to use neovim
for the development of CPython mix between C and Python is really great
with this tool. Also, I wanted to have the description of the C parts,
example, when I have PyArg_ParseTupleAndKeywords under the cursor, with
(n)vim I could use the K shortcut and see the description of this
function via the keywordprg of vim.

But we have the result from Sphinx, because the C part is described in
the .rst files. So, maybe I could develop a wrapper for Sphinx and the
manpages.

So, thank you for your PR.