How does @contextlib.contextmanager turn a generator function into a context manager?

## The problem it solves A context manager is any object with `__enter__` and `__exit__`. Writing one as a class means a `class`, an `__init__` to stash arguments, an `__enter__` that returns something, and an `__exit__` with a three-argument signature — a lot of ceremony for what is usually "do this, then hand control to the block, then always undo it". `contextlib.contextmanager` lets you write that shape as ordinary straight-line code in a generator, where the `yield` marks the hand-off point. ## The mechanical translation Decorating a generator function with `@contextlib.contextmanager` replaces it with a factory. Calling the decorated function does **not** run any of the body; it creates the underlying generator object and wraps it in a helper object that implements the context-manager protocol. * `with cm_factory(...) as value:` calls the factory, then calls `__enter__` on the wrapper. * `__enter__` advances the generator to its first `yield`. Every statement before the `yield` therefore runs as setup, and whatever the `yield` produces becomes the `__enter__` return value — the thing `as` binds. * When the block finishes normally, `__exit__` resumes the generator. The statements after the `yield` run as teardown, and the generator is expected to finish (fall off the end or `return`). * When the block raises, the exception is re-raised *inside the generator, at the `yield` expression*, so the generator can see it with `except`, clean up with `finally`, or let it escape. That last point is the one interviewers push on: the generator is not merely resumed after an error, it is resumed *by having the error raised at the suspension point*. ## Exactly one yield, per call The helper enforces the single-yield contract with clear errors, all of which you can trigger in a REPL: ```python import contextlib @contextlib.contextmanager def never_yields(enabled): if not enabled: return # RuntimeError: generator didn't yield yield @contextlib.contextmanager def yields_twice(): yield 1 yield 2 # RuntimeError: generator didn't stop ``` Entering `never_yields(False)` raises `RuntimeError("generator didn't yield")` because `__enter__` got `StopIteration` instead of a value. Leaving `yields_twice()` raises `RuntimeError("generator didn't stop")` because the generator produced a second value where it should have finished. Both messages are worth recognising on sight — they almost always mean an early `return` on a conditional path or a stray second `yield`, not a bug in the standard library. ## Yielding nothing is normal A plain `yield` with no value yields `None`, which is exactly right for a manager that exists only for its side effects — a timer, a lock, a log-context switch. You then write `with timed():` and omit the `as`. Yielding a value is for managers that hand the block a resource, such as an open connection or a cursor. ## Where the state lives Because the generator's local variables stay alive across the suspension, the setup phase can simply keep what teardown needs in a local: ```python import contextlib, time @contextlib.contextmanager def timed(label): started = time.perf_counter() try: yield finally: print(label, round(time.perf_counter() - started, 3)) ``` With a class, `started` would have to be stored on `self` in `__enter__` and read back in `__exit__`. The generator form removes that bookkeeping entirely, which is most of why it is the default choice for short managers. ## What you give up The object the factory returns is **single-use**: its generator is consumed by the first `with`, so a second `with` on the same object fails. Call the factory again for each block. A generator-based manager is also not reentrant, cannot easily expose extra methods or attributes to the block, and cannot suppress an exception by returning a truthy flag — it suppresses by catching the exception at the `yield` and not re-raising. When you need reuse, reentrancy, inheritance, or a richer object, write the class instead; when you need setup/teardown around a block, the decorator is shorter and harder to get wrong. ## Practical shape The canonical body is three lines of skeleton: setup, `try: yield <value>`, `finally: teardown`. If a manager does not fit that shape — several yields, cleanup that depends on which exception occurred in a complicated way, or state the caller must inspect afterwards — that is the signal to reach for a class-based implementation rather than to bend the generator. ## Naming the thing you are decorating One wording trap is worth fixing early, because interviewers listen for it. `@contextlib.contextmanager` is applied to a generator *function*; what that function returns when called is a context-manager *object*, and inside it lives a generator *object*. "The context manager" in conversation should mean the object the `with` statement operates on, not the function you wrote. Getting those three names straight makes every later question — single use, exception delivery, decorator reuse — easy to state precisely instead of gesturing at "the generator".