A nightly report job's custom iterable caches every row so callers can loop it twice, and memory grows unbounded. How would you redesign the class?

The symptom -- resident memory climbing through the night until the job is killed -- and the cause are one design decision apart. Somebody needed to loop the rows twice, discovered that the object was single-pass, and fixed it by keeping the rows. That works until the report grows. ### The distinction that solves it Re-iterable does not mean *retained*. It means every `__iter__()` call can produce a fresh, independent pass. There are exactly two ways to achieve that: keep the data, or keep the *recipe* for getting it. The first is O(n) memory forever; the second is O(1), and for anything sourced from a file, a query, a socket or an API it is almost always the right one. So invert what the object holds. It stores a factory -- a callable that opens the source, or the path and parameters needed to do so -- and never the rows. `__iter__` is a generator function that opens the source, yields each row, and closes it when the pass ends. ```python class Rows: def __init__(self, open_source): self._open_source = open_source def __iter__(self): with self._open_source() as stream: for line in stream: yield line.rstrip("\n") ``` That class is re-iterable, nested-loop safe, and flat in memory. This is usually called a *restartable iterable*, and it is the standard shape for a lazy view over an external source. ### Resource lifetime, which is where this pattern goes wrong A generator `__iter__` that opens a handle owns that handle for the life of the generator, not the life of the call. Three consequences to be explicit about. **Use `with`, not a bare open.** If the consumer breaks out of the loop early, the generator is left suspended inside the `with`. When it is garbage-collected -- or when someone calls `close()` on it -- `GeneratorExit` is thrown in at the `yield`, the `with` block unwinds, and the handle is released. Without the `with` there is nothing to unwind and the descriptor leaks until process exit. Relying on collection is still nondeterministic under reference cycles, so a consumer holding the generator in a long-lived structure can hold the handle open for a long time; `contextlib.closing` around an explicit iterator, or simply consuming the pass fully, removes the doubt. **Each concurrent pass opens its own handle.** That is the price of independence, and it is the right trade -- but a nested loop over the same object now holds two connections, and a threaded consumer holds one per thread. Bound it: if the source is a connection pool, iterating in a loop over another iteration of the same object can exhaust it. **Nothing runs until the first `next()`.** A generator body is lazy, so the `open` inside `__iter__` does not happen at `__iter__()` time. `obj.__iter__()` succeeding tells you nothing about whether the source exists; the error surfaces at the first element. If early validation matters, do it in `__init__` or in a non-generator `__iter__` that opens the source and returns an inner generator. ### Where materialisation should live Pushing the cache out of the class does not make the second pass free. Name the three options and let the call site choose. *Two passes over the source.* Simplest, and correct when the source is cheap. When it is not -- a 45-second cold start before the first row arrives -- doubling that is a real cost, but at least it is a cost the caller opted into and can measure. *`list()` at the call site.* One line, obvious in review, and the memory is visible where the decision is made rather than hidden inside a class everybody uses. *`itertools.tee`.* Two independent iterators from one pass, but tee buffers every item in the gap between the fastest and slowest consumer. If one consumer runs to completion first, tee has buffered the entire source -- you have reinvented the leak with more machinery. It pays off only when the consumers advance roughly together. Often the best answer is none of them: restructure the two passes into one. A total and a normalisation, or a count and a filter, can usually be computed in a single walk with a couple of accumulators, and then the question disappears. ### Making the contract explicit Whichever way it lands, say so in the type. A restartable view should subclass `collections.abc.Iterable`, be named like a collection, and document *each iteration re-reads the source*. A genuinely single-pass reader should subclass `collections.abc.Iterator`, be named like a cursor, and document that a second pass yields nothing. Callers can then test with `isinstance(obj, collections.abc.Iterator)` before deciding whether they must materialise. Most of these bugs come from a type that never said which it was. ### Confirming the diagnosis first Before redesigning, prove it. Take `tracemalloc` snapshots at intervals during a run and diff them; a retained list of row objects shows up as a single allocation site holding a growing share. That distinguishes the buffering iterable from the other usual suspects -- an unbounded cache, an accumulating log handler, or reference cycles keeping objects alive.