What happens when a Python generator function executes a return statement?

### Two ways a generator body ends A generator's body finishes either by running off the end or by executing `return`. Both produce the same signal to the consumer: the pending `next()` raises `StopIteration`. There is no "final value" slot in the iterator protocol, so termination has to be an exception rather than a sentinel value — any sentinel could collide with a legitimate item. After that, the generator is finished for good. Further `next()` calls raise `StopIteration` again immediately, `gi_frame` is `None`, and `inspect.getgeneratorstate()` reports `GEN_CLOSED`. ### return with a value Python 3.3 made `return value` legal inside a generator (before that it was a `SyntaxError`). The value is **not** yielded — consumers iterating normally never see it. It is stored on the raised exception: ```python def sample(): yield 1 return "done" ``` Iterating that with a `for` loop produces exactly one item, `1`, and the string is discarded along with the swallowed `StopIteration`. To observe it you must catch the exception yourself and read `StopIteration.value` — which is why the returned value is best thought of as an out-of-band result for a delegating caller, not as data for a normal loop. This is the single most common misread in interviews: candidates expect `return "done"` to append `"done"` to the output, by analogy with an ordinary function. It does not appear in `list(sample())` at all. ### Why for loops look like they ignore it `for x in gen:` is defined as: call `iter()`, then call `__next__()` repeatedly, and when `StopIteration` is raised, exit the loop normally. The exception is part of the protocol, not an error condition — which is why nothing is printed, nothing propagates, and a `finally` in the loop still runs. `list()`, `sum()`, tuple unpacking and comprehensions all behave identically because they all drive the same protocol. ### A bare return is a clean early exit Inside a generator, `return` with no value is the idiomatic way to stop producing items early — the equivalent of `break` in the consumer, but decided by the producer: ```python def until_blank(lines): for line in lines: if not line.strip(): return # stop the generator; equivalent to falling off the end yield line ``` It raises `StopIteration` with a value of `None`, and the consumer's loop simply ends. ### PEP 479: StopIteration must not leak Before Python 3.7, a `StopIteration` raised *inside* a generator body by something other than the generator's own completion would propagate and be mistaken for normal termination — so a generator that called `next(inner)` on an exhausted iterator ended silently and truncated its own output, with no error anywhere. Data-loss bugs of that shape were hard to find. PEP 479 changed it: a `StopIteration` that escapes a generator body is replaced by a `RuntimeError` (chained to the original). Opt-in via `from __future__ import generator_stop` in 3.5–3.6, mandatory from 3.7 onward, including 3.14. ```python def leaky(src): while True: yield next(src) # raises RuntimeError once src is exhausted ``` The correct spellings are to iterate with a `for` loop, to pass a default (`next(src, None)`) and check it, or to catch `StopIteration` locally and `return`. Knowing this rule is what separates "return raises StopIteration" as a memorized line from actually understanding the boundary: the generator's *own* completion raises `StopIteration` outward, but any `StopIteration` arriving from within its body is treated as a bug. ### Practical implications * **Do not return data you expect the loop to see.** If a caller needs a summary, yield it as a final item with a distinguishable shape, or expose it as an attribute on an object, rather than relying on the return value. * **Do not raise StopIteration to end a generator.** Use `return`. Raising it explicitly inside the body now triggers the `RuntimeError` conversion. * **Cleanup still runs.** `finally` blocks and `with` bodies in the generator execute as the body unwinds through `return`, which is where resource release belongs. * **Exhaustion is permanent.** Once `StopIteration` has been raised, the generator cannot be restarted; a fresh call to the generator function is the only way to iterate again. ### Checking termination in practice Two quick observations settle most confusion about where a generator ended up. `inspect.getgeneratorstate()` returns `GEN_CLOSED` for a generator whose body has returned, and `gi_frame` is `None` at that point — so "did it finish, or is it parked at a yield?" is directly answerable rather than a guess. And because `StopIteration` is an ordinary exception class, you can always drive the generator with `next()` inside a `try` and inspect what came back, which is the only way to see a returned value without a delegating construct. The overall shape to hold on to: `yield` produces items, `return` produces termination, and the two travel by different channels. Mixing them up — expecting a return to appear as an item, or raising `StopIteration` where a `return` belongs — accounts for most of the surprises in this corner of the language.