[Python-checkins] cpython (merge 3.3 -> default): Merge from 3.3: link to "yield from" examples in yield documentation.

[chris.jerdonek]

http://hg.python.org/cpython/rev/76c5f3371db6
changeset:   81008:76c5f3371db6
parent:      81006:ae1845e4006a
parent:      81007:ecbd29ff2dd5
user:        Chris Jerdonek <chris.jerdonek at gmail.com>
date:        Sun Dec 23 15:35:23 2012 -0800
summary:
  Merge from 3.3: link to "yield from" examples in yield documentation.

files:
  Doc/reference/expressions.rst |  12 +++++++++++-
  Doc/whatsnew/3.3.rst          |  18 +++++++++++-------
  2 files changed, 22 insertions(+), 8 deletions(-)


diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -320,7 +320,8 @@
    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 @@
    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.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::
 
diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst
--- a/Doc/whatsnew/3.3.rst
+++ b/Doc/whatsnew/3.3.rst
@@ -393,14 +393,18 @@
       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 @@
 receive sent and thrown values directly from the calling scope, and
 return a final value to the outer generator::
 
-    >>> def accumulate(start=0):
-    ...     tally = start
+    >>> def accumulate():
+    ...     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 @@
     >>> 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 @@
     ...
     >>> 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

-- 
Repository URL: http://hg.python.org/cpython