From adbda844d0782a64a278561f08bdf7b0d8218bdb Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Fri, 14 Dec 2007 19:03:36 +0000
Subject: [PATCH] Add a section about nested listcomps to the tutorial. Thanks
 to Ian Bruntlett and Robert Lehmann.

---
 Doc/ACKS.txt                    |  1 +
 Doc/tutorial/datastructures.rst | 42 +++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt
index d0c1f31cb95..5f6e12fa922 100644
--- a/Doc/ACKS.txt
+++ b/Doc/ACKS.txt
@@ -28,6 +28,7 @@ docs@python.org), and we'll be glad to correct the problem.
    * Aaron Brancotti
    * Georg Brandl
    * Keith Briggs
+   * Ian Bruntlett
    * Lee Busby
    * Lorenzo M. Catucci
    * Carl Cerecke
diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst
index a5599566edf..c243fe3171c 100644
--- a/Doc/tutorial/datastructures.rst
+++ b/Doc/tutorial/datastructures.rst
@@ -265,6 +265,48 @@ 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