classification
Title: Allow docstrings on dicts and named tuples outside of functions or classes.
Type: enhancement Stage:
Components: Interpreter Core Versions: Python 3.2
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: afoglia, antlong, belopolsky, rhettinger
Priority: normal Keywords: easy

Created on 2010-07-27 18:29 by antlong, last changed 2010-07-27 19:56 by rhettinger. This issue is now closed.

Messages (6)
msg111711 - (view) Author: Anthony Long (antlong) Date: 2010-07-27 18:29
I would like to add docstrings to dicts and named tuples. Dicts can be used to hold many different kinds of information, and docstrings would help to shed light on what the dict does to others.

Named tuples also should have docstrings, since they can also include information which can be explained it great detail within docstrings.
msg111712 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-27 18:35
-1 on dicts

You can simply subclass from dict to add docs.

I think you can add docs to named tuples even without subclassing, but I need to check.
msg111713 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-27 18:44
Indeed, namedtuple auto-generates a doc-string and does not provide a way to customize it.  It sounds reasonable to add a doc argument to namedtuple() function that would control __doc__ of the result.

I am +0 on that.
msg111715 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2010-07-27 18:48
I'm also -1 on dicts -- just use a second dict to hold docstings.

Can you elaborate on your proposal for named tuples? Keep in mind that the API is already somewhat complex and should not be expanded lightly.  

Also, the whole point of named tuples is to allow you to assign attribute names that are self-documenting (otherwise, you would just use t[0], t[1], etc).  So, I'm not sure what the benefit would be for overriding the existing, auto-generated docstring which already gives some useful information (i.e. the position index of the attribute).
msg111720 - (view) Author: Anthony Foglia (afoglia) Date: 2010-07-27 19:35
I could see adding a doc parameter to the collections.namedtuple.  So that

---
>>> Point = collections.namedtuple("Point", ("x", "y"), doc="My point class")
>>> Point.__doc__
My point class
---

(Or it could keep the currently created docstring and append the new doc after an empty line.)

---
>>> Point = collections.namedtuple("Point", ("x", "y"), doc="My point class")
>>> Point.__doc__
Point(x, y)

My point class
---

That being said, I can't think of a strong use case.  If you care enough to add a docstring, you're probably making a type used repeatedly in the code.  In that case, you can just use the verbose parameter and paste the definition into your code.

I'm still in favor of it, simply because it would be a nice parameter to have, but I don't think it's important.
msg111722 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2010-07-27 19:56
Thanks for the idea and quick reply. In view of the discussion, I'm going to reject the feature request.  The trade-off in added API complexity isn't worth the benefit especially given that subclassing already provides an option:

class Point(namedtuple('Point', 'x y z')):
    """Planet location with Sun as center point
    and x-axis passing through Alpha Centauri
    and distance measured in light seconds"""
History
Date User Action Args
2010-07-27 19:56:12rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg111722
2010-07-27 19:35:35afogliasetnosy: + afoglia
messages: + msg111720
2010-07-27 18:48:20rhettingersetassignee: rhettinger

messages: + msg111715
nosy: + rhettinger
2010-07-27 18:44:16belopolskysetkeywords: + easy

messages: + msg111713
2010-07-27 18:35:16belopolskysetnosy: + belopolsky

messages: + msg111712
versions: - Python 2.6, Python 2.5, Python 3.1, Python 2.7, Python 3.3
2010-07-27 18:29:37antlongcreate