When should you replay a one-shot iterator with itertools.tee() rather than list()?

### What tee actually does `itertools.tee(iterable, n=2)` returns `n` independent iterators that all yield the items of one underlying source. It cannot conjure the items twice from a one-shot source, so it does the only thing available: it **buffers**. Internally it keeps the items that the *fastest* branch has already pulled but the *slowest* branch has not yet seen. That single implementation detail decides every question about when to use it. The memory cost is proportional to the **gap between the consumers**, not to the length of the stream. - Branches read almost in step → the buffer holds a handful of items → `tee` is nearly free, even over an enormous or unbounded source. - One branch is drained completely before the other starts → the buffer necessarily grows to the entire stream → you have paid for a list, plus per-item bookkeeping, and got a worse API. CPython's own documentation says as much: when one iterator uses most or all of the data before another starts, `list()` is faster. ```python import itertools source = iter(range(1_000_000)) left, right = itertools.tee(source) next(left) # one item now buffered for right print(list(itertools.islice(left, 3))) # [1, 2, 3] print(list(itertools.islice(right, 3))) # [0, 1, 2] ``` ### The decision, stated as a rule Ask *how the two passes interleave*, then choose: 1. **Lock-step or near-lock-step, and the source is huge, unbounded or expensive to reproduce** → `tee`. Comparing each item with its neighbour, feeding two aggregators that advance together, splitting a stream between a checksum and a writer. 2. **Two full sequential passes over a bounded stream** → `list()` (or `tuple()`). One obvious allocation, no hidden buffer, faster iteration, and the result is re-iterable by every caller thereafter. 3. **The source is cheap to re-read** → re-read it. If the stream comes from a cached fetch running an 83% cache-hit rate, a second traversal costs almost nothing and holds no memory at all. This third option is the one candidates most often forget. 4. **Unbounded and not lock-step** → neither works; redesign so one pass suffices, or bound the replay explicitly with `itertools.islice` and fail loudly on overflow rather than growing until the process is killed. ### A worked example A search-index rebuilder reads a stream of documents and needs two things from it: the newest timestamp in the batch, so it can detect a clock-skew artefact from a machine whose clock ran ahead, and the filtered set of documents to write. Those two needs interleave differently depending on how you frame them. Framed as "compute the maximum, then filter against it", the first pass must finish before the second begins — strictly sequential, so `tee` would buffer the whole batch and `list()` is the honest choice. Framed as "compare each document against its predecessor to flag out-of-order timestamps", the two passes advance together one item apart, and `tee` costs a single buffered item over a stream of any size. Same data, same source, opposite answers — which is why the interview question is about the consumption pattern, not about the function. For the lock-step framing specifically, `itertools.pairwise` (added in Python 3.10) does the job directly and is clearer than hand-rolling it with `tee`. ### The two rules that come with tee **Do not use the original iterator after splitting it.** The branches now own the source and pull from it on demand. Anything you consume directly is simply missing from every branch, with no error to tell you. If you need the raw stream too, make it one of the branches. **Do not share branches across threads.** The branches share one buffer and one source with no locking; concurrent `next()` calls on different branches can raise `RuntimeError` or lose items. The GIL does not save you here, because a single `next()` is not one atomic step. Give each thread its own materialized copy, or serialize access behind a lock you own. ### The judgement an interviewer is listening for The weak answer is "`tee` copies the iterator, so use it whenever you need two passes". The strong answer names the buffer, ties its size to the gap between consumers, and then reaches for the cheapest of re-read / `tee` / materialize based on the actual pattern — while stating the memory bound the choice implies. In a pipeline that anyone else will extend, the deeper point is a contract question: decide whether stages are permitted to demand multiple passes at all, and if they are, where the replay boundary lives and what it is allowed to cost.