Merged revisions 61038,61042-61045,61047,61050,61053,61055-61056,61061-61062,61066,61068,61070,61083,61085,61092-61097,61103-61108 via svnmerge from

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

........
  r61105 | andrew.kuchling | 2008-02-28 15:03:03 +0100 (Thu, 28 Feb 2008) | 1 line

  #2169: make generated HTML more valid
........
  r61106 | jeffrey.yasskin | 2008-02-28 19:03:15 +0100 (Thu, 28 Feb 2008) | 4 lines

  Prevent SocketServer.ForkingMixIn from waiting on child processes that it
  didn't create, in most cases. When there are max_children handlers running, it
  will still wait for any child process, not just handler processes.
........
  r61107 | raymond.hettinger | 2008-02-28 20:41:24 +0100 (Thu, 28 Feb 2008) | 1 line

  Document impending updates to itertools.
........
  r61108 | martin.v.loewis | 2008-02-28 20:44:22 +0100 (Thu, 28 Feb 2008) | 1 line

  Add 2.6aN uuids.
........

1 files changed, 44 insertions, 11 deletions

diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index 73abb89..098972d 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -74,17 +74,30 @@ loops that truncate the stream.
                   yield element
 
 
+.. function:: itertools.chain.from_iterable(iterable)
+
+   Alternate constructor for :func:`chain`.  Gets chained inputs from a 
+   single iterable argument that is evaluated lazily.  Equivalent to::
+
+      @classmethod
+      def from_iterable(iterables):
+          for it in iterables:
+              for element in it:
+                  yield element
+
+   .. versionadded:: 2.6
+
 .. function:: combinations(iterable, r)
 
    Return successive *r* length combinations of elements in the *iterable*.
 
-   Combinations are emitted in a lexicographic sort order.  So, if the 
+   Combinations are emitted in lexicographic sort order.  So, if the 
    input *iterable* is sorted, the combination tuples will be produced
    in sorted order.  
 
    Elements are treated as unique based on their position, not on their
    value.  So if the input elements are unique, there will be no repeat
-   values within a single combination.
+   values in each combination.
 
    Each result tuple is ordered to match the input order.  So, every
    combination is a subsequence of the input *iterable*.
@@ -327,6 +340,26 @@ loops that truncate the stream.
    example :func:`islice` or :func:`takewhile`).
 
 
+.. function:: permutations(iterable[, r])
+
+   Return successive *r* length permutations of elements in the *iterable*.
+
+   If *r* is not specified or is ``None``, then *r* defaults to the length
+   of the *iterable* and all possible full-length permutations 
+   are generated.
+
+   Permutations are emitted in lexicographic sort order.  So, if the 
+   input *iterable* is sorted, the permutation tuples will be produced
+   in sorted order.  
+
+   Elements are treated as unique based on their position, not on their
+   value.  So if the input elements are unique, there will be no repeat
+   values in each permutation.
+
+   Example:  ``permutations(range(3),2) --> (1,2) (1,3) (2,1) (2,3) (3,1) (3,2)``
+
+   .. versionadded:: 2.6
+
 .. function:: product(*iterables[, repeat])
 
    Cartesian product of input iterables.
@@ -553,13 +586,13 @@ which incur interpreter overhead. ::
 
    def ncycles(seq, n):
        "Returns the sequence elements n times"
-       return chain(*repeat(seq, n))
+       return chain.from_iterable(repeat(seq, n))
 
    def dotproduct(vec1, vec2):
        return sum(imap(operator.mul, vec1, vec2))
 
    def flatten(listOfLists):
-       return list(chain(*listOfLists))
+       return list(chain.from_iterable(listOfLists))
 
    def repeatfunc(func, times=None, *args):
        """Repeat calls to func with specified arguments.
@@ -568,8 +601,7 @@ which incur interpreter overhead. ::
        """
        if times is None:
            return starmap(func, repeat(args))
-       else:
-           return starmap(func, repeat(args, times))
+       return starmap(func, repeat(args, times))
 
    def pairwise(iterable):
        "s -> (s0,s1), (s1,s2), (s2, s3), ..."
@@ -583,7 +615,7 @@ which incur interpreter overhead. ::
 
    def roundrobin(*iterables):
        "roundrobin('abc', 'd', 'ef') --> 'a', 'd', 'e', 'b', 'f', 'c'"
-       # Recipe contributed by George Sakkis
+       # Recipe credited to George Sakkis
        pending = len(iterables)
        nexts = cycle(iter(it).next for it in iterables)
        while pending:
@@ -595,8 +627,9 @@ which incur interpreter overhead. ::
                nexts = cycle(islice(nexts, pending))
 
    def powerset(iterable):
-       "powerset('ab') --> set([]), set(['b']), set(['a']), set(['a', 'b'])"
-       skip = object()
-       for t in product(*izip(repeat(skip), iterable)):
-           yield set(e for e in t if e is not skip)
+       "powerset('ab') --> set([]), set(['a']), set(['b']), set(['a', 'b'])"
+       # Recipe credited to Eric Raymond
+       pairs = [(2**i, x) for i, x in enumerate(iterable)]
+       for n in xrange(2**len(pairs)):
+           yield set(x for m, x in pairs if m&n)