How does contextlib.asynccontextmanager turn an async generator function into an async context manager?

### What the decorator actually produces `contextlib.asynccontextmanager` takes an **async generator function** — a function declared with `async def` whose body contains a `yield` — and returns a factory. Calling that factory executes none of the body. It constructs the async generator object and wraps it in a helper that implements the asynchronous context-manager protocol, `__aenter__` and `__aexit__`. The body starts running only when that wrapper is entered by an `async with` statement. ### Entering `__aenter__` drives the generator forward to its single `yield`, awaiting anything the setup code awaits along the way, and returns the yielded value. That value is what the `as` clause binds. This is the whole reason the async variant exists: setup can `await` a handshake, a slow first read, or an asynchronous lock acquisition before handing control to the block. A synchronous `__enter__` has no way to await anything, so a coroutine-based resource cannot be opened from one without blocking the event loop. ### Exiting `__aexit__` resumes the generator. If the block finished normally, the wrapper resumes it and expects it to run to completion. If the block raised, the wrapper **throws that exception into the generator at the point of the `yield`**, so the code around the `yield` observes the failure exactly as if the block had been written inline. This is why teardown must live in a `try: ... finally: ...` around the `yield` rather than simply after it: statements placed after a bare `yield` never execute when the body raises, and the resource is silently left open. Catching the thrown exception at the `yield` and not re-raising it is how the generator form suppresses an exception. ### Exactly one yield, every time The contract is one `yield` per use, on every path. If the generator yields a second time when teardown resumes it, the wrapper raises `RuntimeError` with the message *generator didn't stop*. If a guard clause returns before reaching any `yield`, `__aenter__` raises `RuntimeError` with *generator didn't yield*. Both are contract violations of the decorator, not failures of the underlying resource, and both are usually fixed by restructuring so the single `yield` is unconditional and the conditional logic sits before or after it. ### Single-use objects, reusable functions The decorated *function* is reusable; the object a single call returns is not, because an async generator can be driven to completion only once. Two nested blocks therefore need two calls to the factory. Since **3.10** the returned object can also be used as a decorator on an `async def` function, running the setup before the function body and the teardown after it — handy for cross-cutting instrumentation without an extra `async with` line inside every function: ```python import asyncio from contextlib import asynccontextmanager @asynccontextmanager async def trace(): print("enter") try: yield finally: print("exit") @trace() async def collect(): print("body") asyncio.run(collect()) ``` ### Why prefer it over a hand-written class A class with `__aenter__` and `__aexit__` splits one lifecycle across two methods and forces the shared state into instance attributes. The generator form keeps acquisition and release adjacent in one function, lets ordinary local variables carry the state between them, and reuses the language's own `try`/`finally` semantics for cleanup ordering instead of re-implementing them in `__aexit__`. For most resources — an opened session, a temporary subscription, a timing span, a paused background poller — that is smaller and much harder to get wrong. ### Where the class form still wins The generator form is single-use, so an object meant to be entered repeatedly, or re-entered while already active, needs a real class. Anything that must be inspected between entries — a manager exposing its own attributes or methods — also wants a class, since the decorator hands the block only whatever value was yielded. And a manager that must support both `with` and `async with` needs both method pairs, which one decorated generator cannot provide. ### One practical caution Because the object is produced by calling the factory, forgetting the call is a common error: `async with sensor_session:` on the undecorated *function* fails, while `async with sensor_session("rack-a"):` is correct. The failure is a protocol error rather than a subtle bug, which is fortunate — nothing has been opened yet at that point.