classification
Title: collections.namedtuple: confusing example
Type: Stage:
Components: Documentation Versions: Python 3.2
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: Vincent.Borghi, ash, docs@python, eric.araujo, georg.brandl, rhettinger
Priority: low Keywords:

Created on 2009-08-18 10:38 by ash, last changed 2010-11-21 23:24 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
namedtuple_doc_example.txt ash, 2009-08-20 11:17
Messages (6)
msg91680 - (view) Author: Alexey Shamrin (ash) Date: 2009-08-18 10:38
Maybe it's just me, but it took me several attempts  to understand
namedtuple example in the documentation [1]. The problem is that the
first example uses verbose=True. It's very unusual to get Python source
as the output in Python shell. At first I thought there's some syntax
error in documentation source.

I know that several lines above one can read: "If verbose is true, the
class definition is printed just before being built." But during first
several attempts to understand namedtuple, I skipped it and directly
scrolled to the first example.

I think the first example on namedtuple usage shouldn't use verbose=True.

You could argue I had to try using namedtuple inside Python shell. I
agree. But unfortunately Python 2.6 was not installed on the computer I
was at.

[1]: http://docs.python.org/library/collections.html#collections.namedtuple
msg91692 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2009-08-18 14:43
It seems that it is the API you don't like, not the example.

What is your suggested improvement to the docs?
msg91770 - (view) Author: Alexey Shamrin (ash) Date: 2009-08-20 11:13
Raymond, sorry if I wasn't clear. I'm fine with the API (haven't used it
yet though, because I was stuck after skimming through its documentation).

I suggest to make *first* example simple (without verbose=True) and to
move an example with verbose=True little furthere. I think it should be
something like this:

Example:

.. doctest::
   :options: +NORMALIZE_WHITESPACE

   >>> Point = namedtuple('Point', 'x y')
   >>> p = Point(11, y=22)     # instantiate with positional or keyword
arguments
   >>> p[0] + p[1]             # indexable like the plain tuple (11, 22)
   33
   >>> x, y = p                # unpack like a regular tuple
   >>> x, y
   (11, 22)
   >>> p.x + p.y               # fields also accessible by name
   33
   >>> p                       # readable __repr__ with a name=value style
   Point(x=11, y=22)
   >>> namedtuple('Point', 'x y', verbose=True) # print class definition
   class Point(tuple):
           'Point(x, y)'
   <BLANKLINE>
           __slots__ = ()
   <BLANKLINE>
           _fields = ('x', 'y')
   <BLANKLINE>
           def __new__(_cls, x, y):
               return _tuple.__new__(_cls, (x, y))
   <BLANKLINE>
           @classmethod
           def _make(cls, iterable, new=tuple.__new__, len=len):
               'Make a new Point object from a sequence or iterable'
               result = new(cls, iterable)
               if len(result) != 2:
                   raise TypeError('Expected 2 arguments, got %d' %
len(result))
               return result
   <BLANKLINE>
           def __repr__(self):
               return 'Point(x=%r, y=%r)' % self
   <BLANKLINE>
           def _asdict(t):
               'Return a new dict which maps field names to their values'
               return {'x': t[0], 'y': t[1]}
   <BLANKLINE>
           def _replace(_self, **kwds):
               'Return a new Point object replacing specified fields
with new values'
               result = _self._make(map(kwds.pop, ('x', 'y'), _self))
               if kwds:
                   raise ValueError('Got unexpected field names: %r' %
kwds.keys())
               return result
   <BLANKLINE>
           def __getnewargs__(self):
               return tuple(self)
   <BLANKLINE>
           x = _property(_itemgetter(0))
           y = _property(_itemgetter(1))
msg91771 - (view) Author: Alexey Shamrin (ash) Date: 2009-08-20 11:17
Roundup broke formatting... I've attached a text file with the proposed
example.
msg100077 - (view) Author: Vincent Borghi (Vincent.Borghi) Date: 2010-02-24 23:28
In fact, thanks to the person (Alexey Shamrin) who created 
this issue (issue found while googling for "namedtuple"), 
I have understood the namedtuple example in the 
documentation.
I think like him the verbose=True example that cames
first is very confusing. 

(BTW I must say that the Python reference documentation is usually excellent, so my expectations are high!)
msg122018 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2010-11-21 23:24
See r86650
History
Date User Action Args
2010-11-21 23:24:10rhettingersetstatus: open -> closed
resolution: fixed
messages: + msg122018

versions: - Python 2.6, Python 3.0, Python 3.1, Python 2.7
2010-07-17 22:18:16eric.araujosetnosy: + docs@python
2010-02-24 23:31:02eric.araujosetnosy: + eric.araujo
2010-02-24 23:28:40Vincent.Borghisetnosy: + Vincent.Borghi
messages: + msg100077
2009-09-25 01:18:36rhettingersetpriority: low
2009-08-20 11:17:45ashsetfiles: + namedtuple_doc_example.txt

messages: + msg91771
2009-08-20 11:13:04ashsetmessages: + msg91770
2009-08-18 14:43:18rhettingersetassignee: georg.brandl -> rhettinger

messages: + msg91692
nosy: + rhettinger
2009-08-18 10:38:43ashcreate