Why are generator-based consumer coroutines wrapped in a priming decorator?

### The problem the decorator solves A generator function does not execute when called. It constructs a generator object whose frame is created but not started, and only the first resume runs any of the body. For a *source* generator that is invisible and useful - it is the laziness everyone wants. For a *consumer* generator, one written as `while True: item = yield`, it is a trap: the object is not suspended at the `yield` yet, because it has not reached it. The only legal first resume is one that carries no value, and CPython says so explicitly: `TypeError: can't send non-None value to a just-started generator`. So every consumer generator has an obligatory setup step before it is usable. Leaving that to callers means the same line appears at every construction site, and the failure mode when someone forgets is an exception in production code that looks nothing like 'you forgot to start it'. ### What the decorator does The decorator wraps the generator *function*. The wrapper calls it to obtain the generator object, resumes it once so the body runs up to and parks at the first `yield`, and returns that started object. From the caller's point of view the decorated name is now a factory for ready-to-feed consumers, and the setup step cannot be forgotten because it is no longer at the call site. Apply `functools.wraps` to the wrapper so the original `__name__`, `__doc__` and module survive for tracebacks and introspection. This decorator is a convention with no stdlib home. You will see it under many names across codebases; there is no canonical import for it, which is itself worth saying in an interview, because candidates sometimes assert Python primes generators automatically or that a standard decorator exists for it. ### What it changes about the contract Three consequences are worth naming. First, **the decorated function's return type changes meaning**: it is no longer 'a generator you must start', it is 'a live, running consumer'. That is the point, but it also means the object is stateful from birth, and passing one to two different owners is now a shared-mutable-state bug. Second, **anything before the first `yield` now runs eagerly**, at call time rather than on first use. If the body opens a file, acquires a connection or validates arguments before its first `yield`, that work has silently moved earlier. Usually this is what you want for a consumer - it surfaces a bad argument at construction instead of at the first push - but it must be a deliberate choice. Third, **priming twice is not harmless**. A second bare resume does not re-start anything; it runs the body from the first `yield` to the next one with `None` as the received value, so a consumer that appends what it receives gets a spurious `None` in its buffer. Code that both uses the decorator and defensively advances the generator again at the call site is a real bug, not belt-and-braces. ### Alternatives You do not have to use a generator at all. An ordinary object with a `write()` method and, say, a `flush()` method carries exactly the same state, needs no priming, is trivially testable, and produces stack traces that a reader can follow. In modern async code the same shape is an `async def` consumer draining a queue. Choose the generator version when suspension really is the point - when the consumer's logic is a linear narrative with state between pushes that would otherwise become an explicit state machine, which is precisely the readability argument that made generators feel like coroutines in the first place. ### What to say in an interview The compact answer is: generator bodies are lazy, so a consumer is not listening yet when you create it, and the decorator moves the one-line fix out of every call site and into the definition. Then add the cost - eager pre-`yield` code and a live object handed to the caller - to show you have used it rather than read about it.