Merged revisions 59488-59511 via svnmerge from

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

........
  r59489 | christian.heimes | 2007-12-14 03:33:57 +0100 (Fri, 14 Dec 2007) | 1 line

  Silence a warning about an unsed variable in debug builds
........
  r59490 | christian.heimes | 2007-12-14 03:35:23 +0100 (Fri, 14 Dec 2007) | 2 lines

  Fixed bug #1620: New @spam.getter property syntax modifies the property in place.
  I added also the feature that a @prop.getter decorator does not overwrite the doc string of the property if it was given as an argument to property().
........
  r59491 | raymond.hettinger | 2007-12-14 03:49:47 +0100 (Fri, 14 Dec 2007) | 1 line

  Cleaner method naming convention
........
  r59492 | christian.heimes | 2007-12-14 04:02:34 +0100 (Fri, 14 Dec 2007) | 1 line

  Fixed a warning in _codecs_iso2022.c and some non C89 conform // comments.
........
  r59493 | christian.heimes | 2007-12-14 05:38:13 +0100 (Fri, 14 Dec 2007) | 1 line

  Fixed warning in ssl module
........
  r59500 | raymond.hettinger | 2007-12-14 19:08:20 +0100 (Fri, 14 Dec 2007) | 1 line

  Add line spacing for readability
........
  r59501 | raymond.hettinger | 2007-12-14 19:12:21 +0100 (Fri, 14 Dec 2007) | 3 lines

  Update method names for named tuples.
........
  r59503 | georg.brandl | 2007-12-14 20:03:36 +0100 (Fri, 14 Dec 2007) | 3 lines

  Add a section about nested listcomps to the tutorial.
  Thanks to Ian Bruntlett and Robert Lehmann.
........
  r59504 | raymond.hettinger | 2007-12-14 20:19:59 +0100 (Fri, 14 Dec 2007) | 1 line

  Faster and simpler _replace() method
........
  r59505 | raymond.hettinger | 2007-12-14 22:51:50 +0100 (Fri, 14 Dec 2007) | 1 line

  Add usage note
........
  r59507 | andrew.kuchling | 2007-12-14 23:41:18 +0100 (Fri, 14 Dec 2007) | 1 line

  Remove warning about URL
........
  r59510 | andrew.kuchling | 2007-12-14 23:52:36 +0100 (Fri, 14 Dec 2007) | 1 line

  Bump the version number, and make a few small edits
........
  r59511 | christian.heimes | 2007-12-15 00:42:36 +0100 (Sat, 15 Dec 2007) | 2 lines

  Fixed bug #1628
  The detection now works on Unix with Makefile, Makefile with VPATH and on Windows.
........

1 files changed, 42 insertions, 0 deletions

diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst
index 54d1922..cf9fea3 100644
--- a/Doc/tutorial/datastructures.rst
+++ b/Doc/tutorial/datastructures.rst
@@ -277,6 +277,48 @@ List comprehensions can be applied to complex expressions and nested functions::
    ['3.1', '3.14', '3.142', '3.1416', '3.14159']
 
 
+Nested List Comprehensions
+--------------------------
+
+If you've got the stomach for it, list comprehensions can be nested. They are a
+powerful tool but -- like all powerful tools -- they need to be used carefully,
+if at all.
+
+Consider the following example of a 3x3 matrix held as a list containing three 
+lists, one list per row::
+
+    >>> mat = [
+    ...        [1, 2, 3],
+    ...        [4, 5, 6],
+    ...        [7, 8, 9],
+    ...       ]
+
+Now, if you wanted to swap rows and columns, you could use a list 
+comprehension::
+
+    >>> print [[row[i] for row in mat] for i in [0, 1, 2]]
+    [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
+
+Special care has to be taken for the *nested* list comprehension:
+
+    To avoid apprehension when nesting list comprehensions, read from right to
+    left.
+
+A more verbose version of this snippet shows the flow explicitly::
+
+    for i in [0, 1, 2]:
+        for row in mat:
+            print row[i],
+        print
+
+In real world, you should prefer builtin functions to complex flow statements. 
+The :func:`zip` function would do a great job for this use case::
+
+    >>> zip(*mat)
+    [(1, 4, 7), (2, 5, 8), (3, 6, 9)]
+
+See :ref:`tut-unpacking-arguments` for details on the asterisk in this line.
+
 .. _tut-del:
 
 The :keyword:`del` statement