Terry J. Reedy added the comment:
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.
----------
nosy: +terry.reedy
_______________________________________
Python tracker <[email protected]>
<http://bugs.python.org/issue16669>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
