1berry/cpython
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

eliminate redundancy between yield stmt and yield expr docs (closes #12704)

Browse Source 
Patch by Nikolaus Rath.
This commit is contained in:
Benjamin Peterson 2014-01-26 22:52:08 -05:00
parent 91d4278fba
commit d1c85fd283
2 changed files with 62 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
Doc/reference/expressions.rst
View File

@ -319,27 +319,25 @@ Yield expressions
yield_atom: "(" `yield_expression` ")" yield_atom: "(" `yield_expression` ")"
yield_expression: "yield" [`expression_list` | "from" `expression`] yield_expression: "yield" [`expression_list` | "from" `expression`]
The :keyword:`yield` expression is only used when defining a :term:`generator` The yield expression is only used when defining a :term:`generator` function and
function, thus can only be used in the body of a function definition. Using a yield
and can only be used in the body of a function definition. Using a expression in a function's body causes that function to be a generator.
:keyword:`yield` expression in a function definition is sufficient to cause that
definition to create a generator function instead of a normal function.
When a generator function is called, it returns an iterator known as a When a generator function is called, it returns an iterator known as a
generator. That generator then controls the execution of a generator function. 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 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 time, the execution proceeds to the first yield expression, where it is
is suspended again, returning the value of :token:`expression_list` to suspended again, returning the value of :token:`expression_list` to generator's
generator's caller. By suspended we mean that all local state is retained, caller. By suspended, we mean that all local state is retained, including the
including the current bindings of local variables, the instruction pointer, and current bindings of local variables, the instruction pointer, and the internal
the internal evaluation stack. When the execution is resumed by calling one of evaluation stack. When the execution is resumed by calling one of the
the generator's methods, the function can proceed exactly as if the generator's methods, the function can proceed exactly as if the yield expression
:keyword:`yield` expression was just another external call. The value of the was just another external call. The value of the yield expression after
:keyword:`yield` expression after resuming depends on the method which resumed resuming depends on the method which resumed the execution. If
the execution. If :meth:`~generator.__next__` is used (typically via either a :meth:`~generator.__next__` is used (typically via either a :keyword:`for` or
:keyword:`for` or the :func:`next` builtin) then the result is :const:`None`, the :func:`next` builtin) then the result is :const:`None`. Otherwise, if
otherwise, if :meth:`~generator.send` is used, then the result will be the :meth:`~generator.send` is used, then the result will be the value passed in to
value passed in to that method. that method.
.. index:: single: coroutine .. index:: single: coroutine
@ -349,11 +347,11 @@ suspended. The only difference is that a generator function cannot control
where should the execution continue after it yields; the control is always where should the execution continue after it yields; the control is always
transferred to the generator's caller. transferred to the generator's caller.
:keyword:`yield` expressions are allowed in the :keyword:`try` clause of a yield expressions are allowed in the :keyword:`try` clause of a :keyword:`try`
:keyword:`try` ... :keyword:`finally` construct. If the generator is not ... :keyword:`finally` construct. If the generator is not resumed before it is
resumed before it is finalized (by reaching a zero reference count or by being finalized (by reaching a zero reference count or by being garbage collected),
garbage collected), the generator-iterator's :meth:`~generator.close` method the generator-iterator's :meth:`~generator.close` method will be called,
will be called, allowing any pending :keyword:`finally` clauses to execute. allowing any pending :keyword:`finally` clauses to execute.
When ``yield from <expr>`` is used, it treats the supplied expression as When ``yield from <expr>`` is used, it treats the supplied expression as
a subiterator. All values produced by that subiterator are passed directly a subiterator. All values produced by that subiterator are passed directly
@ -373,12 +371,24 @@ the yield expression. It can be either set explicitly when raising
.. versionchanged:: 3.3 .. versionchanged:: 3.3
Added ``yield from <expr>`` to delegate control flow to a subiterator Added ``yield from <expr>`` to delegate control flow to a subiterator
The parentheses can be omitted when the :keyword:`yield` expression is the The parentheses may be omitted when the yield expression is the sole expression
sole expression on the right hand side of an assignment statement. 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 .. index:: object: generator
Generator-iterator methods Generator-iterator methods
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -395,13 +405,12 @@ is already executing raises a :exc:`ValueError` exception.
.. method:: generator.__next__() .. method:: generator.__next__()
Starts the execution of a generator function or resumes it at the last Starts the execution of a generator function or resumes it at the last
executed :keyword:`yield` expression. When a generator function is resumed executed yield expression. When a generator function is resumed with a
with a :meth:`~generator.__next__` method, the current :keyword:`yield` :meth:`~generator.__next__` method, the current yield expression always
expression always evaluates to :const:`None`. The execution then continues evaluates to :const:`None`. The execution then continues to the next yield
to the next :keyword:`yield` expression, where the generator is suspended expression, where the generator is suspended again, and the value of the
again, and the value of the :token:`expression_list` is returned to :token:`expression_list` is returned to :meth:`next`'s caller. If the
:meth:`next`'s caller. generator exits without yielding another value, a :exc:`StopIteration`
If the generator exits without yielding another value, a :exc:`StopIteration`
exception is raised. exception is raised.
This method is normally called implicitly, e.g. by a :keyword:`for` loop, or This method is normally called implicitly, e.g. by a :keyword:`for` loop, or
@ -411,12 +420,12 @@ is already executing raises a :exc:`ValueError` exception.
.. method:: generator.send(value) .. method:: generator.send(value)
Resumes the execution and "sends" a value into the generator function. The Resumes the execution and "sends" a value into the generator function. The
``value`` argument becomes the result of the current :keyword:`yield` *value* argument becomes the result of the current yield expression. The
expression. The :meth:`send` method returns the next value yielded by the :meth:`send` method returns the next value yielded by the generator, or
generator, or raises :exc:`StopIteration` if the generator exits without raises :exc:`StopIteration` if the generator exits without yielding another
yielding another value. When :meth:`send` is called to start the generator, value. When :meth:`send` is called to start the generator, it must be called
it must be called with :const:`None` as the argument, because there is no with :const:`None` as the argument, because there is no yield expression that
:keyword:`yield` expression that could receive the value. could receive the value.
.. method:: generator.throw(type[, value[, traceback]]) .. method:: generator.throw(type[, value[, traceback]])
@ -478,20 +487,6 @@ For examples using ``yield from``, see :ref:`pep-380` in "What's New in
Python." 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:
Primaries Primaries

57
Doc/reference/simple_stmts.rst
View File

@ -445,53 +445,26 @@ The :keyword:`yield` statement
.. productionlist:: .. productionlist::
yield_stmt: `yield_expression` yield_stmt: `yield_expression`
The :keyword:`yield` statement is only used when defining a generator function, A :keyword:`yield` statement is semantically equivalent to a :ref:`yield
and is only used in the body of the generator function. Using a :keyword:`yield` expression <yieldexpr>`. The yield statement can be used to omit the parentheses
statement in a function definition is sufficient to cause that definition to that would otherwise be required in the equivalent yield expression
create a generator function instead of a normal function. statement. For example, the yield statements ::
When a generator function is called, it returns an iterator known as a generator yield <expr>
iterator, or more commonly, a generator. The body of the generator function is yield from <expr>
executed by calling the :func:`next` function on the generator repeatedly until
it raises an exception.
When a :keyword:`yield` statement is executed, the state of the generator is are equivalent to the yield expression statements ::
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.
The :keyword:`yield` statement is allowed in the :keyword:`try` clause of a (yield <expr>)
:keyword:`try` ... :keyword:`finally` construct. If the generator is not (yield from <expr>)
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.
When ``yield from <expr>`` is used, it treats the supplied expression as Yield expressions and statements are only used when defining a :term:`generator`
a subiterator, producing values from it until the underlying iterator is function, and are only used in the body of the generator function. Using yield
exhausted. 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: .. _raise: