Which return annotation belongs on a @contextlib.contextmanager-decorated function?

### Two functions live in one definition Writing `@contextlib.contextmanager` over `def opened(...)` produces two distinct things, and each has its own type. The **inner** object is a generator function. Its contract is: yield exactly once, and the value yielded is what the `with` statement binds to its `as` target. So its return annotation is a generator annotation — `Iterator[Conn]`, or the fuller `Generator[Conn, None, None]` if you prefer to spell out that nothing is sent in and nothing is returned. It is *not* `Conn`, and it is *not* a context-manager type: the function you wrote really does return a generator, and the decorator is what changes that. The **outer** object is the decorated callable. `contextlib.contextmanager` is itself typed to take a callable returning `Iterator[T]` and give back a callable returning a context manager parameterised by the same `T`. That is why annotating the inner generator is enough: type checkers propagate `T` through the decorator, `with opened("memory") as buffer` infers `Conn` for `buffer` automatically, and you never write the decorated signature by hand. ### When you must name the manager type You need the manager's own name whenever a manager travels as a value rather than being used immediately: a parameter that accepts "anything usable in a `with` block yielding a `Conn`", a registry of managers, a factory that picks one of several. That name is `contextlib.AbstractContextManager[Conn]`; `typing.ContextManager` is a deprecated alias of it, kept since Python 3.9 when the `contextlib` spelling became the preferred one. The type argument is the value handed to `as`, which is worth stating explicitly because it is the second common mistake: `AbstractContextManager[Conn]` does not mean "a manager wrapping a `Conn` object" in some vague sense, it means `__enter__` returns a `Conn`. A manager whose `__enter__` returns nothing useful is `AbstractContextManager[None]`. ### It is a real ABC, not only an annotation `contextlib.AbstractContextManager` is an abstract base class with a `__subclasshook__`: any class defining `__enter__` and `__exit__` is recognised as a subclass structurally, so `issubclass(MyManager, contextlib.AbstractContextManager)` is `True` without registration or inheritance. Inheriting from it explicitly buys a default `__enter__` that returns `self` and marks `__exit__` abstract. For a class-based manager, annotate `__enter__` with `typing.Self` when it returns the instance, so subclasses get the subclass type rather than the base. ### The async twin, and one trap `contextlib.asynccontextmanager` decorates an `async def` containing a single `yield`, so the inner annotation is `AsyncIterator[Conn]`, and the resulting object is named `contextlib.AbstractAsyncContextManager[Conn]` and driven by `async with`. The two families are not interchangeable: a synchronous `with` on an async manager fails at runtime because the object implements `__aenter__` and `__aexit__` rather than `__enter__` and `__exit__`, and a checker with the right annotations catches that before it ships. The trap worth remembering is that a decorated `@contextlib.contextmanager` function returns a **single-use** manager: the object wraps one generator instance, so storing it and entering it twice raises at the second `with`. If a shared component in a codebase hands managers around — say a translation-memory updater that stashes one manager on a module-level object so four services reuse it — the annotation says `AbstractContextManager[Conn]` and looks perfectly correct, while the runtime blows up on reuse. Annotate factories as *callables returning* a manager when re-entry matters, rather than passing one built manager around. ### The __exit__ signature, and what the type argument does not cover A class-based manager's `__exit__` takes three parameters — the exception type, the exception instance and the traceback — and returns `bool | None`, where a true value suppresses the exception propagating out of the `with` block. `AbstractContextManager`'s type argument describes only `__enter__`'s result, so it says nothing about suppression; a manager that swallows exceptions and one that never does share the same annotation. If suppression is part of the contract, it belongs in the docstring, and callers should be suspicious of any manager whose `__exit__` returns anything but `None`. ### Managers as values Two stdlib helpers make the manager-as-value case ordinary. `contextlib.ExitStack` enters managers dynamically and unwinds them in reverse, and `contextlib.nullcontext` supplies a do-nothing manager so an optional resource does not force two code paths — both are natural arguments for `AbstractContextManager[T]`-annotated parameters, and `contextlib.AsyncExitStack` plays the same role for the async family. That is the practical reason to know the name at all: as soon as managers are stored, chosen between, or passed to a helper, the annotation has to name the manager rather than the resource. ### Sanity checks before you ship the annotation Ask three questions of any manager signature. What does `as` bind — that is the type argument. Is this `with` or `async with` — that picks `AbstractContextManager` or `AbstractAsyncContextManager`, and the inner generator annotation `Iterator[T]` or `AsyncIterator[T]`. Will the object be entered more than once — if so, hand around a factory rather than a manager built by `@contextlib.contextmanager`, whose object is spent after one use.