Why does a StopIteration raised inside a generator body surface as RuntimeError?

`StopIteration` occupies an unusual position in Python: it is an exception used as a control-flow signal. An iterator raises it to say "finished", a `for` loop catches it and exits, and a generator object raises it at its boundary when its function body returns. Because that same exception type means "I am done" at the boundary, an accidental `StopIteration` from *inside* the body used to be read as the same message. ### The bug PEP 479 was written to kill Consider a chat-transcript archiver whose generator reads a header line and then the body line that follows it: ```python def records(lines): it = iter(lines) for header in it: body = next(it) # raises StopIteration on a truncated file yield header, body ``` On a well-formed file this works. On a file truncated mid-record - a crash during a write, a partial upload, a locale-dependent format that split a record across a boundary - the inner `next()` finds nothing. Before PEP 479, that `StopIteration` propagated out of the generator frame, the consumer's `for` loop interpreted it as the normal end signal, and the loop finished quietly. The caller got fewer records than the file contained, with no traceback, no log line, and no exit code. Silent truncation is the worst failure mode there is: the pipeline downstream sees a plausible, smaller dataset. The same trap appeared wherever a helper that could raise `StopIteration` was called inside a generator - a shared parsing function, a `__next__` implementation reused across modules, a callback whose contract nobody had read. ### What Python does now Since the change became default behaviour in Python 3.7 (it was available from 3.5 via `from __future__ import generator_stop`), a `StopIteration` that escapes a generator frame is caught by the interpreter and replaced with `RuntimeError`, whose message is `generator raised StopIteration`. The original exception is attached as `__cause__`, so the traceback shows both the `RuntimeError` at the generator boundary and the `StopIteration` beneath it, at the line that actually raised. Silent truncation became a loud, located failure. On 3.14 this is simply how generators behave; there is no way back and no flag to restore the old semantics. Asynchronous generators carry the equivalent guard for their own end-of-iteration exception. ### How to write code that never hits it The two-argument `next()` is the tidy fix, because it converts exhaustion into a value the generator can act on: ```python _END = object() def records(lines): it = iter(lines) for header in it: body = next(it, _END) if body is _END: return # a clean end of the generator yield header, body ``` `return` inside a generator is the *correct* way to finish: it produces the boundary `StopIteration` through the proper channel, so no `RuntimeError` is involved. A `try/except StopIteration:` around the inner call that then returns (or logs and returns) is equally valid, and is the better shape when you want to record that the input was truncated rather than accept it as normal. What you must not do is let the exception travel out of the body. ### The limits of the protection PEP 479 guards **generator frames**. A hand-written iterator class whose `__next__` internally calls something that raises `StopIteration` still has the old failure mode: the exception is exactly the signal `__next__` is supposed to give, so the consuming loop ends early and quietly. If you write `__next__` by hand, guard the inner calls yourself. Second, `RuntimeError` is a broad type. Code that wraps a pipeline in `except RuntimeError:` and continues will re-hide the very failure PEP 479 exposed. If you catch it, catch it narrowly and inspect `__cause__` before deciding it is benign. Third, this is a *runtime* change, not a static one: nothing warns you at import time that a helper you call can raise `StopIteration`. Tests that only feed well-formed input never reach the path, which is why the truncated-input case belongs in the test suite explicitly. ### Why it is a senior question It requires knowing that `StopIteration` is a signal rather than an error, recognising the silent-truncation class of bug, and knowing the version at which the semantics changed. The candidate who has debugged a pipeline that quietly produced 80% of its expected rows answers it from memory.