From 9bd3508530cfcb1687c4a4cddd12a09f234026ee Mon Sep 17 00:00:00 2001
From: Raymond Hettinger <python@rcn.com>
Date: Tue, 9 Mar 2010 09:01:46 +0000
Subject: [PATCH] Add nicer docstrings to namedtuples(). Provides better
 tooltips and looks better in help().

---
 Doc/library/collections.rst | 7 +++++--
 Lib/collections.py          | 5 ++++-
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index c73fbff636d..a3bbc63cbbe 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -679,6 +679,7 @@ Example:
            _fields = ('x', 'y')
    <BLANKLINE>
            def __new__(_cls, x, y):
+               'Create a new instance of Point(x, y)'
                return _tuple.__new__(_cls, (x, y))
    <BLANKLINE>
            @classmethod
@@ -690,6 +691,7 @@ Example:
                return result
    <BLANKLINE>
            def __repr__(self):
+               'Return a nicely formatted representation string'
                return 'Point(x=%r, y=%r)' % self
    <BLANKLINE>
            def _asdict(self):
@@ -704,10 +706,11 @@ Example:
                return result
    <BLANKLINE>
            def __getnewargs__(self):
+               'Return self as a plain tuple.   Used by copy and pickle.'
                return tuple(self)
    <BLANKLINE>
-           x = _property(_itemgetter(0))
-           y = _property(_itemgetter(1))
+           x = _property(_itemgetter(0), doc='Alias for field number 0')
+           y = _property(_itemgetter(1), doc='Alias for field number 1')
 
    >>> p = Point(11, y=22)     # instantiate with positional or keyword arguments
    >>> p[0] + p[1]             # indexable like the plain tuple (11, 22)
diff --git a/Lib/collections.py b/Lib/collections.py
index 12f3ccad67f..1b80ef8f075 100644
--- a/Lib/collections.py
+++ b/Lib/collections.py
@@ -230,6 +230,7 @@ def namedtuple(typename, field_names, verbose=False, rename=False):
         __slots__ = () \n
         _fields = %(field_names)r \n
         def __new__(_cls, %(argtxt)s):
+            'Create new instance of %(typename)s(%(argtxt)s)'
             return _tuple.__new__(_cls, (%(argtxt)s)) \n
         @classmethod
         def _make(cls, iterable, new=tuple.__new__, len=len):
@@ -239,6 +240,7 @@ def namedtuple(typename, field_names, verbose=False, rename=False):
                 raise TypeError('Expected %(numfields)d arguments, got %%d' %% len(result))
             return result \n
         def __repr__(self):
+            'Return a nicely formatted representation string'
             return '%(typename)s(%(reprtxt)s)' %% self \n
         def _asdict(self):
             'Return a new OrderedDict which maps field names to their values'
@@ -250,9 +252,10 @@ def namedtuple(typename, field_names, verbose=False, rename=False):
                 raise ValueError('Got unexpected field names: %%r' %% kwds.keys())
             return result \n
         def __getnewargs__(self):
+            'Return self as a plain tuple.  Used by copy and pickle.'
             return tuple(self) \n\n''' % locals()
     for i, name in enumerate(field_names):
-        template += '        %s = _property(_itemgetter(%d))\n' % (name, i)
+        template += "        %s = _property(_itemgetter(%d), doc='Alias for field number %d')\n" % (name, i, i)
     if verbose:
         print template