Raymond Hettinger added the comment: 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." ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue16669> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
