This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author terry.reedy
Recipients Ankur.Ankan, eric.snow, giampaolo.rodola, gvanrossum, rhettinger, serhiy.storchaka, terry.reedy
Date 2013-12-05.01:40:18
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1386207620.89.0.520050652004.issue16669@psf.upfronthosting.co.za>
In-reply-to
Content
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.
History
Date User Action Args
2013-12-05 01:40:21terry.reedysetrecipients: + terry.reedy, gvanrossum, rhettinger, giampaolo.rodola, eric.snow, serhiy.storchaka, Ankur.Ankan
2013-12-05 01:40:20terry.reedysetmessageid: <1386207620.89.0.520050652004.issue16669@psf.upfronthosting.co.za>
2013-12-05 01:40:20terry.reedylinkissue16669 messages
2013-12-05 01:40:18terry.reedycreate