#
6.8 The `yield` statement

  yield_stmt | ::= | yield_expression

  Download entire grammar as text.

The `yield` statement is only used when defining a generator function, and is only used in the body of the generator function. Using a `yield` statement 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 generator iterator, or more commonly, a generator. The body of the generator function is executed by calling the generator's `next()` method repeatedly until it raises an exception.

When a `yield` statement is executed, the state of the generator is frozen and the value of expression_list is returned to `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 `next()` is invoked, the function can proceed exactly as if the `yield` statement were just another external call.

As of Python version 2.5, the `yield` statement is now allowed in the `try` clause of a `try` ... `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 `close()` method will be called, allowing any pending `finally` clauses to execute.

Note: In Python 2.2, the `yield` statement is only allowed when the `generators` feature has been enabled. It will always be enabled in Python 2.3. This `__future__` import statement can be used to enable the feature:

    from __future__ import generators

See Also:

PEP 0255, Simple Generators
  The proposal for adding generators and the `yield` statement to Python.

PEP 0342, Coroutines via Enhanced Generators
  The proposal that, among other generator enhancements, proposed allowing `yield` to appear inside a `try` ... `finally` block.