[Python-checkins] cpython (3.3): eliminate redundancy between yield stmt and yield expr docs (closes #12704)
benjamin.peterson
python-checkins at python.org
Mon Jan 27 04:58:52 CET 2014
http://hg.python.org/cpython/rev/e02da391741f
changeset: 88756:e02da391741f
branch: 3.3
parent: 88754:6e4b94019eae
user: Benjamin Peterson <benjamin at python.org>
date: Sun Jan 26 22:52:08 2014 -0500
summary:
eliminate redundancy between yield stmt and yield expr docs (closes #12704)
Patch by Nikolaus Rath.
files:
Doc/reference/expressions.rst | 99 ++++++++++-----------
Doc/reference/simple_stmts.rst | 57 +++---------
2 files changed, 62 insertions(+), 94 deletions(-)
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -319,27 +319,25 @@
yield_atom: "(" `yield_expression` ")"
yield_expression: "yield" [`expression_list` | "from" `expression`]
-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.
+The yield expression is only used when defining a :term:`generator` function and
+thus can only be used in the body of a function definition. Using a yield
+expression in a function's body causes that function to be a generator.
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. If :meth:`~generator.__next__` is used (typically via either a
-:keyword:`for` or the :func:`next` builtin) then the result is :const:`None`,
-otherwise, if :meth:`~generator.send` is used, then the result will be the
-value passed in to that method.
+time, the execution proceeds to the first 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 yield expression
+was just another external call. The value of the yield expression after
+resuming depends on the method which resumed the execution. If
+:meth:`~generator.__next__` is used (typically via either a :keyword:`for` or
+the :func:`next` builtin) then the result is :const:`None`. Otherwise, if
+:meth:`~generator.send` is used, then the result will be the value passed in to
+that method.
.. index:: single: coroutine
@@ -349,11 +347,11 @@
where should the execution continue after it yields; the control is always
transferred to the generator's caller.
-:keyword:`yield` expressions are 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:`~generator.close` method
-will be called, allowing any pending :keyword:`finally` clauses to execute.
+yield expressions are 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:`~generator.close` method will be called,
+allowing any pending :keyword:`finally` clauses to execute.
When ``yield from <expr>`` is used, it treats the supplied expression as
a subiterator. All values produced by that subiterator are passed directly
@@ -373,12 +371,24 @@
.. versionchanged:: 3.3
Added ``yield from <expr>`` to delegate control flow to a subiterator
-The parentheses can be omitted when the :keyword:`yield` expression is the
-sole expression on the right hand side of an assignment statement.
+The parentheses may be omitted when the yield expression is the sole expression
+on the right hand side of an assignment statement.
+
+.. 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.
+
+ :pep:`0380` - Syntax for Delegating to a Subgenerator
+ The proposal to introduce the :token:`yield_from` syntax, making delegation
+ to sub-generators easy.
.. index:: object: generator
-
Generator-iterator methods
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -395,13 +405,12 @@
.. 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:`~generator.__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`
+ executed yield expression. When a generator function is resumed with a
+ :meth:`~generator.__next__` method, the current yield expression always
+ evaluates to :const:`None`. The execution then continues to the next 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
@@ -411,12 +420,12 @@
.. 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.
+ *value* argument becomes the result of the current 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 yield expression that
+ could receive the value.
.. method:: generator.throw(type[, value[, traceback]])
@@ -478,20 +487,6 @@
Python."
-.. 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.
-
- :pep:`0380` - Syntax for Delegating to a Subgenerator
- The proposal to introduce the :token:`yield_from` syntax, making delegation
- to sub-generators easy.
-
-
.. _primaries:
Primaries
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -445,53 +445,26 @@
.. productionlist::
yield_stmt: `yield_expression`
-The :keyword:`yield` statement is only used when defining a generator function,
-and is only used in the body of the generator function. Using a :keyword:`yield`
-statement in a function definition is sufficient to cause that definition to
-create a generator function instead of a normal function.
+A :keyword:`yield` statement is semantically equivalent to a :ref:`yield
+expression <yieldexpr>`. The yield statement can be used to omit the parentheses
+that would otherwise be required in the equivalent yield expression
+statement. For example, the yield statements ::
-When a generator function is called, it returns an iterator known as a generator
-iterator, or more commonly, a generator. The body of the generator function is
-executed by calling the :func:`next` function on the generator repeatedly until
-it raises an exception.
+ yield <expr>
+ yield from <expr>
-When a :keyword:`yield` statement is executed, the state of the generator is
-frozen and the value of :token:`expression_list` is returned to :meth:`next`'s
-caller. By "frozen" we mean that all local state is retained, including the
-current bindings of local variables, the instruction pointer, and the internal
-evaluation stack: enough information is saved so that the next time :func:`next`
-is invoked, the function can proceed exactly as if the :keyword:`yield`
-statement were just another external call.
+are equivalent to the yield expression statements ::
-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.
+ (yield <expr>)
+ (yield from <expr>)
-When ``yield from <expr>`` is used, it treats the supplied expression as
-a subiterator, producing values from it until the underlying iterator is
-exhausted.
+Yield expressions and statements are only used when defining a :term:`generator`
+function, and are only used in the body of the generator function. Using yield
+in a function definition is sufficient to cause that definition to create a
+generator function instead of a normal function.
- .. versionchanged:: 3.3
- Added ``yield from <expr>`` to delegate control flow to a subiterator
-
-For full details of :keyword:`yield` semantics, refer to the :ref:`yieldexpr`
-section.
-
-.. 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.
-
- :pep:`0380` - Syntax for Delegating to a Subgenerator
- The proposal to introduce the :token:`yield_from` syntax, making delegation
- to sub-generators easy.
-
+For full details of :keyword:`yield` semantics, refer to the
+:ref:`yieldexpr` section.
.. _raise:
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list