Message205978
A few quick thoughts:
* Everyone can agree "docstrings are good".
* I disagree with Ned that the current docstrings
are ugly or not useful. The class docstring is
shown by tooltips and is immediately useful to
someone making a instance. The attribute docstrings
add value by indicating position (named tuples are
fundamentally sequences, so the position matters).
* Unlike method docstrings, the attribute docstrings
are only visible in help(). As TJR noted, most
users will never see them or expect them.
* That said, tuples are like records in a database
and it is common in the database world to have a
data dictionary that provides more detail than
the field name.
* In general, I'm unsympathetic to "my automatically
generated docs aren't pretty". My experience with
auto-generated docs suggests that you almost always
have to manually make improvements. The nature of
auto-generated code or docs is that the output is
usable but not pretty.
* I am very sympathetic to how difficult it is to add
or modify property docstrings after the fact. This
isn't unique to named tuples but the problem is felt
more acutely.
* The intended ways to extend named tuples is to either
1) subclass the NT and change anything that doesn't
suit your needs, or 2) use the generated source as
a starting point and edit it directly. In the case
of a module docstring, either method works fine. In
the case of attribute docstrings, the first method is
a PITA because you have to recreate the whole property
definition.
* To me, that is the only point in favor of the feature
request. Where the implementation currently makes
something difficult, it would be nice to provide a
smoother, standardized solution.
* That said, there are downsides to make the patch.
It complicates the API, making named tuples harder
to teach, to learn, or to remember. The docs for
named tuples are turning into a book. Factories
that provide too many options are harder to use.
In addition, the patch further complicates the
named tuple implementation. And to the extent that
users provide multi-line docstrings for the attributes,
the visual appearance of the generated code gets ugly
and the visual appearance of the call to named tuple
factory becomes somewhat awkward.
* There is no question about whether the functionality
might occassionally be useful and whether it is currently
hard to implement using subclassing. The question boils
down to balancing aesthetics trade-offs (i.e. improving
the aesthetic of automated generated docs versus hurting
the aesthetics of 1) the factory function signature,
2) the generated code (which is intende to be viewed,
studied, cut-and-pasted, exec'ed, etc), and complexity
of the collections module code for named tuples.
* Since 2.7 was long since released, the earliest anyone
would see a change in Python 3.5. The other ships have
already sailed.
* One last thought. I worry about over-parameterizing
named tuples. If I had it to do over again, I wouldn't
have added the *rename* option. The *verbose* option
is no longer necessary because of the *_source* attribute.
There is a *module* parameter being added that will only
be used in rare cases. There was a requests for a
*type_specifiers* parameter to type check all of the
arguments (similar to the functionality in argparse).
There was a request for *format_specfiers* to control
how the named tuple display (this is mainly useful
for printing a list of named tuples in the form of
a table with nicely aligned columns).
* Individually, those parameter requests sound reasonable
(i.e. they have legitimate use cases). Collectively,
they are an API train wreck. It doesn't pay to try
to please all of the people, all of the time.
* I'm inclined to say that most or of these aren't
worth it and simply acknowledge that "once in a while
some aspect of named tuples isn't a convenient as you
would like, but that there are other compensating
aesthetics." |
|
Date |
User |
Action |
Args |
2013-12-12 20:29:58 | rhettinger | set | recipients:
+ rhettinger, gvanrossum, terry.reedy, giampaolo.rodola, nedbat, eric.snow, serhiy.storchaka, pconnell, Ankur.Ankan |
2013-12-12 20:29:58 | rhettinger | set | messageid: <1386880198.7.0.856902114828.issue16669@psf.upfronthosting.co.za> |
2013-12-12 20:29:58 | rhettinger | link | issue16669 messages |
2013-12-12 20:29:57 | rhettinger | create | |
|