Yield

Specification: Yield

 A new statement is introduced:
 

 

 yield_stmt:    "yield" expression_list
 

 

 "yield" is a new keyword, so a future statement[8] is needed to phase
 

 this in:  in the initial release, a module desiring to use generators
 

 must include the line
 

 

 from __future__ import generators
 

 

 near the top (see
 
  PEP 236
 
 [8]) for details).  Modules using the
 

 identifier "yield" without a future statement will trigger warnings.
 

 In the following release, yield will be a language keyword and the
 

 future statement will no longer be needed.
 

 

 The yield statement may only be used inside functions.  A function that
 

 contains a yield statement is called a generator function.  A generator
 

 function is an ordinary function object in all respects, but has the
 

 new CO_GENERATOR flag set in the code object's co_flags member.
 

 

 When a generator function is called, the actual arguments are bound to
 

 function-local formal argument names in the usual way, but no code in
 

 the body of the function is executed.  Instead a generator-iterator
 

 object is returned; this conforms to the iterator protocol[6], so in
 

 particular can be used in for-loops in a natural way.  Note that when
 

 the intent is clear from context, the unqualified name "generator" may
 

 be used to refer either to a generator-function or a generator-
 

 iterator.
 

 

 Each time the .next() method of a generator-iterator is invoked, the
 

 code in the body of the generator-function is executed until a yield
 

 or return statement (see below) is encountered, or until the end of
 

 the body is reached.
 

 

 If a yield statement is encountered, the state of the function 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.
 

 

 Restriction:  A yield statement is not allowed in the try clause of a
 

 try/finally construct.  The difficulty is that there's no guarantee
 

 the generator will ever be resumed, hence no guarantee that the finally
 

 block will ever get executed; that's too much a violation of finally's
 

 purpose to bear.
 

 

 Restriction:  A generator cannot be resumed while it is actively
 

 running:
 

 

 >>> def g():
 

 ...     i = me.next()
 

 ...     yield i
 

 >>> me = g()
 

 >>> me.next()
 

 Traceback (most recent call last):
 

 ...
 

 File "<string>", line 2, in g
 

 ValueError: generator already executing