[issue16669] Docstrings for namedtuple

[Terry J. Reedy]

Terry J. Reedy added the comment:

Serhiy: I am not familiar with C PyStructSequence and how an instance of one appears in Python code. I agree that more methods should have docstrings.

Guido:
1. I posted on SO the simple Py 3 solution that replaces the previously posted wrapper solutions needed for Py 2.

2. Much of what you do not like is standard Sphinx/help behavior that would be unchanged by Serhiy's patch. The first line for a class is always "class <classname>(<base_classes>)". The first line is followed by the docstring, so the class name is repeated if and only if it is repeated in the docstring (as for list, see below). The __new__/__init__ signature is given here if and only it is in the docstring. Otherwise, one has to look down for the method. The method signatures are never on the first line. Examples:

>>> help(list)
Help on class list in module builtins:

class list(object)
 |  list() -> new empty list
 |  list(iterable) -> new list initialized from iterable's items
...
>>> class C:
        "doc string"
	def __init__(self, a, b): pass

>>> help(C)
Help on class C in module __main__:

class C(builtins.object)
 |  doc string
 |
 |  Methods defined here:
 |  
 |  __init__(self, a, b)
...

3. ?? Python 3 has many improvements and we will add more.
---

I am still of the opinion that property usage should be a mostly transparent implementation detail. Point classes could have 4 instance attributes: x, y, r, and theta, with a particular implementation using 0 to 4 properties.  All attributes should be documented regardless of the number of properties, which currently means listing them in the class docstring. A library could have more than one than one implementation.

As for named tuples, I believe (without trying) that the name to index mapping could be done with __gettattr__ and a separate dict. If so, there would be no property docstrings and hence no field docstrings to worry about ;-).
---

There have been requests for data attribute docstrings (without the bother and inefficiency of replacing a simple attribute with a property). Since such a docstring would have to be attached to the fixed attribute name, rather than the variable attribute value, I believe a string subclass would suffice, to be used as needed. The main problem is a decent syntax to add a docstring to a simple (assignment) statement.  

If the general problem were solved, I would choose Serhiy's option B for namedtuple.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue16669>
_______________________________________