One-Shot Iteration Traps

## The symptom The bug looks like data loss. A function builds a generator object, one piece of code loops over it to count or validate, a second piece of code loops over it to do the real work, and the second loop sees nothing at all. No exception, no warning, no traceback — just an empty result where a full one was expected. ```python def flag_names(rows): for row in rows: yield row.strip() gen = flag_names([" beta_ui ", "new_pricing"]) print(sum(1 for _ in gen)) # 2 print(list(gen)) # [] -- the values are gone ``` ## Why it happens A `for` loop begins by calling `iter()` on whatever it is given. For a list, `iter()` constructs a brand-new `list_iterator` positioned at index 0, so every loop is independent. For a generator object, `iter()` returns *the generator object itself* — a generator is its own iterator, and `iter(gen) is gen` is `True`. There is therefore exactly one cursor, shared by every consumer, and it only moves forward. Each `next()` resumes the suspended function body until the next `yield`. When the body finally returns, `next()` raises `StopIteration`, and the generator marks itself finished and drops its execution frame. Every subsequent `next()` raises `StopIteration` immediately. There is no `reset()`, no `seek(0)`, no way back: the state that would let it replay the values no longer exists. ## Why it is silent `StopIteration` is the normal end-of-iteration signal, not an error. `for` catches it and exits cleanly, so a loop over an exhausted generator is indistinguishable from a loop over an empty source. The consequences are quiet and wrong rather than loud: `sum()` returns `0`, `any()` returns `False`, `all()` returns `True`, `list()` returns `[]`, `"x" in gen` returns `False`, and `len(list(gen))` reports zero items where the data really did exist a moment earlier. `max()` and `min()` are the only common builtins that complain, and only because an empty sequence has no maximum. The patterns that trigger it in real code are always the same shape: count first and then process; validate first and then write; log a preview and then send; or simply pass the same generator object to two helper functions. ## The four ways out **1. Materialise it.** If the data is bounded and small enough to hold, `values = list(gen)` once, then reuse `values` freely. This is the right default for hundreds or thousands of small records; it trades memory for a container that can be measured, indexed and looped as often as you like. **2. Rebuild it.** Call the generator function again. `flag_names(rows)` is cheap; each call returns a new generator object with a fresh frame. This works only if the underlying source is itself re-readable — rebuilding over an already-drained iterator just produces another empty generator. **3. Hand out a factory, not an iterator.** Return an object that builds a new generator on every `__iter__` call. Callers then get list-like "loop me as often as you want" semantics while the values stay lazy: ```python class FlagNames: def __init__(self, rows): self._rows = rows def __iter__(self): return (row.strip() for row in self._rows) ``` **4. `itertools.tee`.** When two consumers genuinely need the same live stream, `tee` splits one iterator into independent branches — at the price of buffering whatever the leading branch has consumed and the lagging one has not. Useful for two consumers running roughly in step; a poor substitute for `list()` otherwise, and after teeing you must stop touching the original iterator. ## Defending against it Because the failure is silent, the cheap protection is to make the contract explicit. Annotate a return type as `list[str]` when you promise re-iteration and as `Iterator[str]` when you do not, name the parameter honestly, and at an API boundary that must survive being looped twice, check `isinstance(value, collections.abc.Iterator)` and materialise. Checking for `Iterable` proves nothing — every iterator is also an iterable; `Iterator` is the check that says "this argument is one-shot". And write the test that iterates the result twice: that single test turns an invisible data-loss bug into a red build.