Add and update itertools recipes.

diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index f83e9762a22d20cff51eb2c08cf5c7d695f226b7..663b93c919abd0d05a4ebe681dedaf67583f6009 100644 (file)
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -703,7 +703,8 @@ which incur interpreter overhead.
        return sum(imap(operator.mul, vec1, vec2))
 
    def flatten(listOfLists):
-       return list(chain.from_iterable(listOfLists))
+       "Flatten one level of nesting"
+       return chain.from_iterable(listOfLists)
 
    def repeatfunc(func, times=None, *args):
        """Repeat calls to func with specified arguments.
@@ -790,6 +791,27 @@ which incur interpreter overhead.
        except exception:
            pass
 
+   def random_product(*args, **kwds):
+       "Random selection from itertools.product(*args, **kwds)"
+       pools = map(tuple, args) * kwds.get('repeat', 1)
+       return map(random.choice, pools)
+
+   def random_permuation(iterable, r=None):
+       "Random selection from itertools.permutations(iterable, r)"
+       pool = list(iterable)
+       r = len(pool) if r is None else r
+       return random.sample(pool, r)
+
+   def random_combination(iterable, r):
+       "Random selection from itertools.combinations(iterable, r)"
+       pool = list(iterable)
+       return sorted(random.sample(pool, r), key=pool.index)
+
+   def random_combination_with_replacement(iterable, r):
+       "Random selection from itertools.combinations_with_replacement(iterable, r)"
+       pool = list(iterable)
+       return sorted(imap(random.choice, [pool]*r), key=pool.index)
+
 Note, many of the above recipes can be optimized by replacing global lookups
 with local variables defined as default values.  For example, the
 *dotproduct* recipe can be written as::