Add and update itertools recipes.

diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index f3e107e2baa34ac7e5b03ea741a623e913c1b189..993e86ef01266ed223e922d494e3fea5fa1d8d68 100644 (file)
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -669,7 +669,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.
@@ -778,6 +779,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::