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 eric.snow, giampaolo.rodola, rhettinger, serhiy.storchaka, terry.reedy
Date 2012-12-15.20:32:35
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1355603556.09.0.994575691774.issue16669@psf.upfronthosting.co.za>
In-reply-to
Content
I think this should be rejected and closed since the 'enhancement' looks worse to me than what we can do now.

1. Most data attributes cannot have individual docstrings, so I expect the class docstring to list and possibly explain the data attributes. 

2. In the process of responding to #16670, I finally read the namedtuple doc. I notice that it already generates default one-line .__doc__ attributes for both the class and properties. For Point, the class docstring is 'Point(x, y)', which will often be good enough. 

3. If the person creating the class does not think this sufficient, the replacement is likely to be multiple lines. This is awkward for a constructor argument. There is a reason we put docstrings *after* the header, not *in* the header.

4. The class docstring is easily replaced by assignment. So I would write Eric's example as

Point = namedtuple('Point', 'x y')
Point.__doc__ = '''\
A 2-dimensional coordinate

x - the abscissa
y - the ordinate'''

This does not create a second new class and is not a 'trick'.

5. The property docstrings have the form 'Alias for field number 0'. I do not consider replacing them an issue. If a true data attribute is replaced by a property, the act of replacement should be transparent. That is the point of properties. So there is no expectation that the attribute should suddenly grow a docstring, I presume that is why property docstrings are not used much. The default for named tuples gives information that is peculiarly relevant to named tuples and that should be generated automatically. As I said before, I think the prose explanation of field names belongs in the class doc.
History
Date User Action Args
2012-12-15 20:32:36terry.reedysetrecipients: + terry.reedy, rhettinger, giampaolo.rodola, eric.snow, serhiy.storchaka
2012-12-15 20:32:36terry.reedysetmessageid: <1355603556.09.0.994575691774.issue16669@psf.upfronthosting.co.za>
2012-12-15 20:32:36terry.reedylinkissue16669 messages
2012-12-15 20:32:35terry.reedycreate