From 2654b86e88aa14f0916cfa10ecdbc0852e7e6795 Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Sun, 23 Dec 2012 15:31:57 -0800 Subject: Link to "yield from" examples in yield documentation. This commit also simplifies the more advanced "yield from" example and removes unused function parameters. --- 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 index 41523cb9c3..429fee4e99 100644 --- a/Doc/reference/expressions.rst +++ b/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:: diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst index 4b9dc9c694..4ea49956f8 100644 --- a/Doc/whatsnew/3.3.rst +++ b/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): - ... 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 @@ 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 -- cgit v1.2.1