Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in

Unified Diff: Doc/reference/expressions.rst

Issue 11682: PEP 380 reference implementation for 3.3
Patch Set: Created 8 years, 1 month ago
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -56,7 +56,7 @@
.. productionlist::
atom: `identifier` | `literal` | `enclosure`
enclosure: `parenth_form` | `list_display` | `dict_display` | `set_display`
- : | `generator_expression` | `yield_atom`
+ : | `generator_expression` | `yield_expression`
.. _atom-identifiers:
@@ -317,133 +317,41 @@
pair: generator; function
.. productionlist::
- yield_atom: "(" `yield_expression` ")"
- yield_expression: "yield" [`expression_list`]
+ yield_expression: "(" `yield_stmt` ")"
-The :keyword:`yield` expression is only used when defining a 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.
+The :keyword:`yield` statement appears only in generator functions and is used
+to pause the execution of a function and pass a value to the caller. The
eric.araujo 2011/09/21 16:25:47 This file uses two spaces after dots, please do th
+behaviour of :keyword:`yield` depends on the generator method that was called
+and is described in detail `elsewhere <yield>`_. Here, only the behaviour of
+:keyword:`yield` as an expression is documented.
-When a generator function is called, it returns an iterator known as a
-generator. That generator then controls the execution of a generator function.
-The execution starts when one of the generator's methods is called. At that
-time, the execution proceeds to the first :keyword:`yield` expression, where it
-is suspended again, returning the value of :token:`expression_list` to
-generator's caller. By suspended we mean that all local state is retained,
-including the current bindings of local variables, the instruction pointer, and
-the internal evaluation stack. When the execution is resumed by calling one of
-the generator's methods, the function can proceed exactly as if the
-:keyword:`yield` expression was just another external call. The value of the
-:keyword:`yield` expression after resuming depends on the method which resumed
-the execution.
+When :token:`yield from <yield_from>` is used, the :attr:`~StopIteration.value`
+attribute of :exc:`StopIteration` used to signal the exhaustion of the
+sub-generator becomes the value of the yield expression. It can be either set
+explicitely when raising :exc:`StopIteration`, or automatically when the
+sub-generator is a generator, by returning a value from the sub-generator
-.. index:: single: coroutine
+When a :token:`normal yield <yield_arg>` is used, the value of the
+:token:`yield_expression` depends on the generator method that was called. When
+the generator's :obj:`~generator.__next__` method is used, the value of the
+yield expression is :const:`None`, this is the most common case. When the
+generator's :obj:`send(value) <generator.send>` method is used, the ``value``
eric.araujo 2011/09/21 16:25:47 I’d say :meth:`~generator.send`
+passed as an argument becomes the value of the :token:`yield_expression`.
-All of this makes generator functions quite similar to coroutines; they yield
-multiple times, they have more than one entry point and their execution can be
-suspended. The only difference is that a generator function cannot control
-where should the execution continue after it yields; the control is always
-transferred to the generator's caller.
+The other two generator methods cause an exception to be raised at the point of
+the yield statement. :meth:`~generator.throw` takes exception details as
+arguments and is used to raise an arbitrary expression at the point where the
+generator function is stopped after :keyword:`yield`. :meth:`~generator.close`
+is used to finalize generators and causes a :exc:`GeneratorExit` exception to be
+raised at the point of the :keyword:`yield` statement.
-The :keyword:`yield` statement is allowed in the :keyword:`try` clause of a
-:keyword:`try` ... :keyword:`finally` construct. If the generator is not
-resumed before it is finalized (by reaching a zero reference count or by being
-garbage collected), the generator-iterator's :meth:`close` method will be
-called, allowing any pending :keyword:`finally` clauses to execute.
-.. index:: object: generator
-The following generator's methods can be used to control the execution of a
-generator function:
-.. index:: exception: StopIteration
-.. method:: generator.__next__()
- Starts the execution of a generator function or resumes it at the last
- executed :keyword:`yield` expression. When a generator function is resumed
- with a :meth:`__next__` method, the current :keyword:`yield` expression
- always evaluates to :const:`None`. The execution then continues to the next
- :keyword:`yield` expression, where the generator is suspended again, and the
- value of the :token:`expression_list` is returned to :meth:`next`'s caller.
- If the generator exits without yielding another value, a :exc:`StopIteration`
- exception is raised.
- This method is normally called implicitly, e.g. by a :keyword:`for` loop, or
- by the built-in :func:`next` function.
-.. method:: generator.send(value)
- Resumes the execution and "sends" a value into the generator function. The
- ``value`` argument becomes the result of the current :keyword:`yield`
- expression. The :meth:`send` method returns the next value yielded by the
- generator, or raises :exc:`StopIteration` if the generator exits without
- yielding another value. When :meth:`send` is called to start the generator,
- it must be called with :const:`None` as the argument, because there is no
- :keyword:`yield` expression that could receive the value.
-.. method:: generator.throw(type[, value[, traceback]])
- Raises an exception of type ``type`` at the point where generator was paused,
- and returns the next value yielded by the generator function. If the generator
- exits without yielding another value, a :exc:`StopIteration` exception is
- raised. If the generator function does not catch the passed-in exception, or
- raises a different exception, then that exception propagates to the caller.
-.. index:: exception: GeneratorExit
-.. method:: generator.close()
- Raises a :exc:`GeneratorExit` at the point where the generator function was
- paused. If the generator function then raises :exc:`StopIteration` (by
- exiting normally, or due to already being closed) or :exc:`GeneratorExit` (by
- not catching the exception), close returns to its caller. If the generator
- yields a value, a :exc:`RuntimeError` is raised. If the generator raises any
- 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.
-Here is a simple example that demonstrates the behavior of generators and
-generator functions::
- >>> def echo(value=None):
- ... print("Execution starts when 'next()' is called for the first time.")
- ... try:
- ... while True:
- ... try:
- ... value = (yield value)
- ... except Exception as e:
- ... value = e
- ... finally:
- ... print("Don't forget to clean up when 'close()' is called.")
- ...
- >>> generator = echo(1)
- >>> print(next(generator))
- Execution starts when 'next()' is called for the first time.
- 1
- >>> print(next(generator))
- None
- >>> print(generator.send(2))
- 2
- >>> generator.throw(TypeError, "spam")
- TypeError('spam',)
- >>> generator.close()
- Don't forget to clean up when 'close()' is called.
+The parentheses can be ommited when the :token:`yield statement <yield_stmt>`
+occurs in a top-level expression on the right-hand side of an assignment.
.. seealso::
- :pep:`0255` - Simple Generators
- The proposal for adding generators and the :keyword:`yield` statement to Python.
- :pep:`0342` - Coroutines via Enhanced Generators
- The proposal to enhance the API and syntax of generators, making them
- usable as simple coroutines.
+ The documentation for the :keyword:`yield` statement.
eric.araujo 2011/09/21 16:25:47 I’d remove the seealso section entirely; your doc
.. _primaries:

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+