Why is AsyncIterator[bytes], not Awaitable[bytes], the return annotation for an async generator?

### Two protocols that both start with `async def` Python has two asynchronous protocols and they do not overlap. The **awaitable** protocol is `__await__`. An object implementing it can appear after `await`, which suspends the caller until one result is produced. `collections.abc.Awaitable[T]` is the annotation for "something that, when awaited, gives a `T`". `collections.abc.Coroutine[YieldType, SendType, ReturnType]` is the narrower one describing specifically a coroutine object, which additionally supports `send()`, `throw()` and `close()`. The **async-iteration** protocol is `__aiter__` plus `__anext__`, where `__anext__` returns an awaitable and signals the end by raising `StopAsyncIteration`. `collections.abc.AsyncIterable[T]` promises `__aiter__`; `collections.abc.AsyncIterator[T]` promises both, exactly mirroring the synchronous `Iterable` / `Iterator` split. `async for` drives this protocol, not the awaitable one. ### Which object does the call produce? An `async def` function whose body contains no `yield` is a **coroutine function**; calling it produces a coroutine object, and awaiting that object once produces the value the body returned. The convention is to annotate the awaited result: `async def fetch(name: str) -> str`. A checker infers `Coroutine[Any, Any, str]` at the call site by itself, so writing `-> Awaitable[str]` on the definition is both redundant and wrong — it would mean the function synchronously returns an awaitable. An `async def` whose body contains `yield` is an **async generator function**. Calling it produces an async generator object immediately, without running a line of the body and without any awaiting. There is no result to `await`, so `Awaitable[bytes]` is simply a false description; the accurate one is `AsyncIterator[bytes]`. Use `AsyncGenerator[bytes, ControlType]` only when callers push values in with `asend()`. Note the asymmetry with synchronous generators: `AsyncGenerator` has two parameters, not three, because an async generator cannot `return` a value — that is a syntax error. ### Where Awaitable does belong `Awaitable[T]` is the right annotation on the *consuming* side. A helper that takes work and awaits it should accept `Awaitable[str]`, so callers may pass a coroutine object, a task created from one, a future, or any custom object with `__await__`. Demanding `Coroutine[Any, Any, str]` there would reject `asyncio.Task` and `asyncio.Future`, which are awaitable but are not coroutine objects — a genuine and common bug in shared helper libraries. Narrow to `Coroutine` only if the body really calls `send()`, `throw()` or `close()`, or passes the object somewhere that requires a raw coroutine. The symmetric mistake runs the other way: a plain `def` that builds and returns a coroutine or a task without awaiting it should be annotated `-> Awaitable[str]`, because that is exactly what it hands back. ### A streaming signature in practice A translation-memory updater that streams segments out of storage is naturally `async def segments(...) -> AsyncIterator[bytes]`, consumed with `async for`. Annotate it `Awaitable[bytes]` and every caller who tries to `await` it gets a runtime `TypeError` — the async generator object has no `__await__` — while a caller who correctly writes `async for` is flagged by the checker instead. Both halves of the codebase end up arguing with the annotation rather than with each other. ### Spelling notes Prefer `collections.abc` imports since Python 3.9 (PEP 585); the `typing` names are deprecated aliases. Since Python 3.13, PEP 696 defaults mean `AsyncGenerator[bytes]` is accepted as `AsyncGenerator[bytes, None]`. Contextlib's async helper follows the same pattern: an `async def` with a single `yield` under `contextlib.asynccontextmanager` is itself annotated `AsyncIterator[T]`. ### The consuming side, symmetrically Parameters follow the same widest-honest-promise rule as the synchronous protocols. A helper that only writes `async for chunk in source:` should take `AsyncIterable[bytes]`, because `async for` needs `__aiter__` and nothing more. Take `AsyncIterator[bytes]` when the body drives the stream itself — awaiting `__anext__` explicitly, or pulling a header off the front and passing the remainder along — since that annotation also warns callers the argument will be consumed. And an async generator is single-pass exactly as a synchronous one is: two `async for` loops over the same object give you the items once and then nothing. ### Naming the object a plain def returns The mirror-image case is easy to get backwards. A synchronous `def` that creates work without awaiting it — building a coroutine object, wrapping it in a task, returning a future from a client — genuinely does return an awaitable, so `-> Awaitable[str]` is correct there. The test is mechanical: ask what the *call expression* evaluates to. `async def f() -> str` means `await f()` is a `str`; `def g() -> Awaitable[str]` means `g()` is a thing you still have to await. Getting this backwards produces the classic runtime error where a coroutine object is used as if it were its result, and a checker with correct annotations catches it immediately. ### Why the distinction bites in production Streaming and request-response APIs fail differently. An awaited call either produces a value or raises; an async stream can end early, be abandoned mid-iteration, or need explicit `aclose()` so its `finally` blocks run. Annotating a stream as an awaitable hides that entire class of concern from every reader of the signature, which is a documentation failure long before it is a type-checking one.