From: Raymond Hettinger <python@rcn.com>
Date: Fri, 22 Feb 2008 19:50:06 +0000 (+0000)
Subject: Document itertools.product().
X-Git-Tag: v2.6a1~113
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c5705a823bb200b48417677f8ef3ca6833ace4bb;p=python

Document itertools.product().
---

diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index d8faba7fa1..7d1ec96640 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -302,6 +302,29 @@ loops that truncate the stream.
 
    .. versionadded:: 2.6
 
+.. function:: product(*iterables)
+
+   Cartesian product of input iterables.
+
+   Equivalent to nested for-loops in a generator expression. For example,
+   ``product(A, B)`` returns the same as ``((x,y) for x in A for y in B)``.
+
+   The leftmost iterators are in the outermost for-loop, so the output tuples
+   cycle in a manner similar to an odometer (with the rightmost element
+   changing on every iteration).
+
+   Equivalent to (but without building the entire result in memory)::
+
+       def product(*args):
+           pools = map(tuple, args)
+           if pools:            
+               result = [[]]
+               for pool in pools:
+                   result = [x+[y] for x in result for y in pool]
+               for prod in result:
+                   yield tuple(prod)
+
+   .. versionadded:: 2.6
 
 .. function:: repeat(object[, times])
 
diff --git a/Misc/NEWS b/Misc/NEWS
index 2e63c82281..5848dbaa5b 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -635,6 +635,9 @@ Library
 - itertools.count() is no longer bounded to LONG_MAX.  Formerly, it raised
   an OverflowError.  Now, automatically shifts from ints to longs.
 
+- Added itertools.product() which forms the Cartesian product of
+  the input iterables.
+
 - Patch #1541463: optimize performance of cgi.FieldStorage operations.
 
 - Decimal is fully updated to the latest Decimal Specification (v1.66).