Merge from 3.3: link to "yield from" examples in yield documentation.

Doc/reference/expressions.rst

@@ -320,7 +320,8 @@ Yield expressions
    yield_atom: "(" `yield_expression` ")"
    yield_expression: "yield" [`expression_list` | "from" `expression`]
 
-The :keyword:`yield` expression is only used when defining a generator function,
+The :keyword:`yield` expression is only used when defining a :term:`generator`
+function,
 and can only be used in the body of a function definition.  Using a
 :keyword:`yield` expression in a function definition is sufficient to cause that
 definition to create a generator function instead of a normal function.
@@ -438,6 +439,12 @@ is already executing raises a :exc:`ValueError` exception.
    other exception, it is propagated to the caller.  :meth:`close` does nothing
    if the generator has already exited due to an exception or normal exit.
 
+
+.. index:: single: yield; examples
+
+Examples
+^^^^^^^^
+
 Here is a simple example that demonstrates the behavior of generators and
 generator functions::
 
@@ -465,6 +472,9 @@ generator functions::
    >>> generator.close()
    Don't forget to clean up when 'close()' is called.
 
+For examples using ``yield from``, see :ref:`pep-380` in "What's New in
+Python."
+
 
 .. seealso::
 

Doc/whatsnew/3.3.rst

@@ -393,14 +393,18 @@ inspection of exception attributes::
       PEP written and implemented by Antoine Pitrou
 
 
+.. index::
+   single: yield; yield from (in What's New)
+
 .. _pep-380:
 
 PEP 380: Syntax for Delegating to a Subgenerator
 ================================================
 
-PEP 380 adds the ``yield from`` expression, allowing a generator to delegate
+PEP 380 adds the ``yield from`` expression, allowing a :term:`generator` to
+delegate
 part of its operations to another generator. This allows a section of code
-containing 'yield' to be factored out and placed in another generator.
+containing :keyword:`yield` to be factored out and placed in another generator.
 Additionally, the subgenerator is allowed to return with a value, and the
 value is made available to the delegating generator.
 
@@ -421,15 +425,15 @@ However, unlike an ordinary loop, ``yield from`` allows subgenerators to
 receive sent and thrown values directly from the calling scope, and
 return a final value to the outer generator::
 
-    >>> def accumulate(start=0):
+    >>> def accumulate():
-    ...     tally = start
+    ...     tally = 0
     ...     while 1:
     ...         next = yield
     ...         if next is None:
     ...             return tally
     ...         tally += next
     ...
-    >>> def gather_tallies(tallies, start=0):
+    >>> def gather_tallies(tallies):
     ...     while 1:
     ...         tally = yield from accumulate()
     ...         tallies.append(tally)
@@ -437,7 +441,7 @@ return a final value to the outer generator::
     >>> tallies = []
     >>> acc = gather_tallies(tallies)
     >>> next(acc) # Ensure the accumulator is ready to accept values
-    >>> for i in range(10):
+    >>> for i in range(4):
     ...     acc.send(i)
     ...
     >>> acc.send(None) # Finish the first tally
@@ -446,7 +450,7 @@ return a final value to the outer generator::
     ...
     >>> acc.send(None) # Finish the second tally
     >>> tallies
-    [45, 10]
+    [6, 10]
 
 The main principle driving this change is to allow even generators that are
 designed to be used with the ``send`` and ``throw`` methods to be split into