Syntax:

yield [expression list]

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 the expression list is returned to next's caller. That is, 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. For Python 2.3 and later, it is always enabled. This \_\_future\_\_ import statement can be used to enable the feature in Python 2.2:

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.