[issue16669] Docstrings for namedtuple

Changes by Raymond Hettinger : -- resolution: rejected -> fixed status: open -> closed ___ Python tracker ___ ___ Python-bugs-list mai

[issue16669] Docstrings for namedtuple

Raymond Hettinger added the comment: The need for this may be eliminated by issue 24064. Then we change the docstrings just like any other object with no special rules or methods. -- ___ Python tracker __

[issue16669] Docstrings for namedtuple

Changes by Raymond Hettinger : -- Removed message: http://bugs.python.org/msg242119 ___ Python tracker ___ ___ Python-bugs-list mailin

[issue16669] Docstrings for namedtuple

Raymond Hettinger added the comment: Ideally, I prefer to stick with either a separate customization step or with the original __new__ constructor, and that uses **kwds so we can use a standard syntax for the name value pairs and to allow that possibility of someone passing in an existing dict

[issue16669] Docstrings for namedtuple

Changes by Raymond Hettinger : -- Removed message: http://bugs.python.org/msg242118 ___ Python tracker ___ ___ Python-bugs-list mailin

[issue16669] Docstrings for namedtuple

Raymond Hettinger added the comment: Sorry Peter, I don't like that variant and want to stick with a separate customization step that uses **kwds so we can use normal syntax for the name value pairs and to allow that possibility of someone passing in an existing dict using NT.set_docstrings(**

[issue16669] Docstrings for namedtuple

Peter Otten added the comment: Here's a variant that builds on your code, but makes for a nicer API. Single-line docstrings can be passed along with the attribute name, and with namedtuple.with_docstrings(... all info required to build the class ...) from a user perspective the factory looks l

[issue16669] Docstrings for namedtuple

Raymond Hettinger added the comment: FWIW, here's a proposed new classmethod that makes it possible to easily customize the field docstrings but without cluttering the API of the factory function: @classmethod def _set_docstrings(cls, **docstrings): '''Customize the field docst

[issue16669] Docstrings for namedtuple

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

[issue16669] Docstrings for namedtuple

Changes by Raymond Hettinger : -- versions: +Python 3.5 -Python 3.4 ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscri

[issue16669] Docstrings for namedtuple

Serhiy Storchaka added the comment: Unhide this discussion. -- ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue16669] Docstrings for namedtuple

Changes by Serhiy Storchaka : -- status: closed -> open ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: https:/

[issue16669] Docstrings for namedtuple

Ned Batchelder added the comment: I'll add my voice to those asking for a way to put docstrings on namedtuples. As it is, namedtuples get automatic docstrings that seem to me to be almost worse than none. Sphinx produces this: ``` class Key Key(scope, user_id, block_scope_id, field_name

[issue16669] Docstrings for namedtuple

Guido van Rossum added the comment: It was never about signature detection for me -- what gave you that idea? I simply want to have the option to put individual docstrings on the properties generated by namedtuple. -- ___ Python tracker

[issue16669] Docstrings for namedtuple

Terry J. Reedy added the comment: I think we can now agree that docstrings other than the class docstring (used as a fallback) are not relevant to signature detection. And Raymond gave namedtuple classes the docstring needed as a fallback. We are off-issue here, but idlelib.CallTips.get_argspe

[issue16669] Docstrings for namedtuple

Changes by Phil Connell : -- nosy: +pconnell ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.pytho

[issue16669] Docstrings for namedtuple

Guido van Rossum added the comment: On Wed, Dec 4, 2013 at 10:25 PM, Terry J. Reedy wrote: > I am familiar with running Sphinx on .rst files, but not on docstrings. > It looks like the docstrings use .rst markup. (Is this allowed in the > stdlib?) I'm not sure if it is allowed, but it is cert

[issue16669] Docstrings for namedtuple

Terry J. Reedy added the comment: > I find the help() output way too verbose with its endless listing of all the > built-in behaviors.) Then you might agree to a patch, on a separate issue. Let's set help aside for the moment. I am familiar with running Sphinx on .rst files, but not on docstr

[issue16669] Docstrings for namedtuple

Guido van Rossum added the comment: On Wed, Dec 4, 2013 at 5:40 PM, Terry J. Reedy wrote: > 1. I posted on SO the simple Py 3 solution that replaces the previously > posted wrapper solutions needed for Py 2. Thanks, that will give people some pointers for Python 3. We need folks to upvote it.

[issue16669] Docstrings for namedtuple

Terry J. Reedy added the comment: 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 neede

[issue16669] Docstrings for namedtuple

Guido van Rossum added the comment: I don't know if it's worth reopening this, but I had a need for generating docs including attribute docstrings for a namedtuple class using Sphinx, and I noticed a few things... (1) Regarding there not being demand: There's a StackOverflow question for this

[issue16669] Docstrings for namedtuple

Changes by Raymond Hettinger : -- resolution: -> rejected status: open -> closed ___ Python tracker ___ ___ Python-bugs-list mailing

[issue16669] Docstrings for namedtuple

Changes by Ankur Ankan : -- nosy: +Ankur.Ankan ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.pyth

[issue16669] Docstrings for namedtuple

Serhiy Storchaka added the comment: > 1. Most data attributes cannot have individual docstrings, so I expect the > class docstring to list and possibly explain the data attributes. But almost all PyStructSequence field have individual docstrings. > This does not create a second new class and

[issue16669] Docstrings for namedtuple

Eric Snow added the comment: +1, Terry -- ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.or

[issue16669] Docstrings for namedtuple

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 t

[issue16669] Docstrings for namedtuple

Giampaolo Rodola' added the comment: > I don't think it is worth complicating the API for this. There have > been zero requests for this functionality. Even the doc field of > property() is rarely used. +1 -- nosy: +giampaolo.rodola ___ Python tr

[issue16669] Docstrings for namedtuple

Serhiy Storchaka added the comment: Yes, we can use inheritance trick/idiom to specify a class docstring. But there are no way to specify attribute docstrings. I encountered this when rewriting some C implemented code to Python. PyStructSequence allows you to specify docstrings for a class and

[issue16669] Docstrings for namedtuple

Eric Snow added the comment: What is wrong with the following? class Point(namedtuple('Point', 'x y')): """A 2-dimensional coordinate x - the abscissa y - the ordinate """ This seems more clear to me. namedtuple is in some ways a quick-and-dirty type, essentially a more true

[issue16669] Docstrings for namedtuple

Raymond Hettinger added the comment: I don't think it is worth complicating the API for this. There have been zero requests for this functionality. Even the doc field of property() is rarely used. -- assignee: -> rhettinger priority: normal -> low __

[issue16669] Docstrings for namedtuple

Changes by Serhiy Storchaka : Added file: http://bugs.python.org/file28295/namedtuple_docstrings_tuples_seq.patch ___ Python tracker ___ ___

[issue16669] Docstrings for namedtuple

New submission from Serhiy Storchaka: Here are two patches which implementation two different interface for same feature. In first patch you can use *doc* and *field_docs* arguments to specify namedtuple class docstring and field docstrings. For example: Point = namedtuple('Point', 'x y',