Merged revisions 59605-59624 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r59606 | georg.brandl | 2007-12-29 11:57:00 +0100 (Sat, 29 Dec 2007) | 2 lines

  Some cleanup in the docs.
........
  r59611 | martin.v.loewis | 2007-12-29 19:49:21 +0100 (Sat, 29 Dec 2007) | 2 lines

  Bug #1699: Define _BSD_SOURCE only on OpenBSD.
........
  r59612 | raymond.hettinger | 2007-12-29 23:09:34 +0100 (Sat, 29 Dec 2007) | 1 line

  Simpler documentation for itertools.tee().  Should be backported.
........
  r59613 | raymond.hettinger | 2007-12-29 23:16:24 +0100 (Sat, 29 Dec 2007) | 1 line

  Improve docs for itertools.groupby().  The use of xrange(0) to create a unique object is less obvious than object().
........
  r59620 | christian.heimes | 2007-12-31 15:47:07 +0100 (Mon, 31 Dec 2007) | 3 lines

  Added wininst-9.0.exe executable for VS 2008
  Integrated bdist_wininst into PCBuild9 directory
........
  r59621 | christian.heimes | 2007-12-31 15:51:18 +0100 (Mon, 31 Dec 2007) | 1 line

  Moved PCbuild directory to PC/VS7.1
........
  r59622 | christian.heimes | 2007-12-31 15:59:26 +0100 (Mon, 31 Dec 2007) | 1 line

  Fix paths for build bot
........
  r59623 | christian.heimes | 2007-12-31 16:02:41 +0100 (Mon, 31 Dec 2007) | 1 line

  Fix paths for build bot, part 2
........
  r59624 | christian.heimes | 2007-12-31 16:18:55 +0100 (Mon, 31 Dec 2007) | 1 line

  Renamed PCBuild9 directory to PCBuild
........

1 files changed, 64 insertions, 0 deletions

diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst
index cf9fea3..206f056 100644
--- a/Doc/tutorial/datastructures.rst
+++ b/Doc/tutorial/datastructures.rst
@@ -350,6 +350,70 @@ is assigned to it).  We'll find other uses for :keyword:`del` later.
 
 
 
+Tuples and Sequences
+====================
+
+We saw that lists and strings have many common properties, such as indexing and
+slicing operations.  They are two examples of *sequence* data types (see
+:ref:`typesseq`).  Since Python is an evolving language, other sequence data
+types may be added.  There is also another standard sequence data type: the
+*tuple*.
+
+A tuple consists of a number of values separated by commas, for instance::
+
+   >>> t = 12345, 54321, 'hello!'
+   >>> t[0]
+   12345
+   >>> t
+   (12345, 54321, 'hello!')
+   >>> # Tuples may be nested:
+   ... u = t, (1, 2, 3, 4, 5)
+   >>> u
+   ((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
+
+As you see, on output tuples are always enclosed in parentheses, so that nested
+tuples are interpreted correctly; they may be input with or without surrounding
+parentheses, although often parentheses are necessary anyway (if the tuple is
+part of a larger expression).
+
+Tuples have many uses.  For example: (x, y) coordinate pairs, employee records
+from a database, etc.  Tuples, like strings, are immutable: it is not possible
+to assign to the individual items of a tuple (you can simulate much of the same
+effect with slicing and concatenation, though).  It is also possible to create
+tuples which contain mutable objects, such as lists.
+
+A special problem is the construction of tuples containing 0 or 1 items: the
+syntax has some extra quirks to accommodate these.  Empty tuples are constructed
+by an empty pair of parentheses; a tuple with one item is constructed by
+following a value with a comma (it is not sufficient to enclose a single value
+in parentheses). Ugly, but effective.  For example::
+
+   >>> empty = ()
+   >>> singleton = 'hello',    # <-- note trailing comma
+   >>> len(empty)
+   0
+   >>> len(singleton)
+   1
+   >>> singleton
+   ('hello',)
+
+The statement ``t = 12345, 54321, 'hello!'`` is an example of *tuple packing*:
+the values ``12345``, ``54321`` and ``'hello!'`` are packed together in a tuple.
+The reverse operation is also possible::
+
+   >>> x, y, z = t
+
+This is called, appropriately enough, *sequence unpacking*. Sequence unpacking
+requires the list of variables on the left to have the same number of elements
+as the length of the sequence.  Note that multiple assignment is really just a
+combination of tuple packing and sequence unpacking!
+
+There is a small bit of asymmetry here:  packing multiple values always creates
+a tuple, and unpacking works for any sequence.
+
+.. XXX Add a bit on the difference between tuples and lists.
+
+
 .. _tut-sets:
 
 Sets