What must an object implement for `await obj` to be legal in Python?

### Awaitable is a protocol, not a type `await` is not restricted to coroutine objects. Its operand must be an **awaitable**, which the language defines structurally. Three categories satisfy it: * **Coroutine objects** returned by calling an `async def` function. * **Objects implementing `__await__`** - a plain (non-async) method returning an iterator. * **Generator-based coroutines**, ordinary generator functions decorated with `types.coroutine`. This is the legacy path from before native syntax; the decorator asyncio once provided for the same purpose was removed in 3.11, but `types.coroutine` remains and is still how some low-level library code hands raw yields to the loop. `collections.abc.Awaitable` is the abstract base class for the concept - a class with `__await__` is a virtual subclass of it - and `inspect.isawaitable(obj)` is the runtime predicate. Note that a coroutine object satisfies it while a coroutine *function* does not: the function is not awaitable, its return value is. ### Why an iterator The design deliberately reuses the generator machinery. Driving a coroutine means repeatedly calling `send` on it and receiving whatever it yields. When execution hits `await x`, control delegates into `x.__await__()`, and every value that iterator yields passes straight through to the driver. When the iterator raises `StopIteration`, its `value` becomes the value of the `await` expression: ```python class Constant: def __init__(self, value): self.value = value def __await__(self): return iter([]) # never suspends # a `return self.value` inside a generator would set StopIteration.value ``` The practically useful version is a generator function, where `return` sets the result: ```python class Ready: def __init__(self, value): self.value = value def __await__(self): yield # suspend once; give the loop a turn return self.value # becomes the result of `await Ready(x)` ``` Two mistakes are common here. `__await__` must **not** be `async def` - that would return a coroutine object rather than an iterator, and awaiting the instance fails. And whatever is yielded is interpreted by whichever framework is driving; `asyncio` treats a bare `yield` as "relinquish one loop iteration" and a yielded `Future` as "wake me when this completes". Yielding some other object to an asyncio loop is an error, which is why awaitables written for one event-loop framework are usually not portable to another. ### Where the protocol shows up in practice You rarely write `__await__` in application code, and that is exactly why this is a differentiator rather than a gate. Where it matters: * **Futures and tasks.** `asyncio.Future` implements `__await__`, and `asyncio.Task` inherits it. That is the whole mechanism by which `await some_task` works: it is not special-cased syntax, just the protocol. * **Objects that are usable both ways.** A method can return an object that is both awaitable and, say, a context manager or an iterable, so the same call reads naturally in more than one style. Library code does this to offer `await conn.execute(...)` and `async with conn.execute(...)` from one return value. * **Adapters.** Wrapping a callback-based API in an object whose `__await__` yields a future is the standard bridge from callback style into async/await. ### Neighbouring dunders worth distinguishing `__await__` is not the only async protocol, and interviewers sometimes probe the family. `__aenter__` and `__aexit__` make an *asynchronous* context manager, used with `async with`; both are `async def`, so they return awaitables. `__aiter__` and `__anext__` make an asynchronous iterator for `async for`; `__anext__` is awaited each round and signals exhaustion with `StopAsyncIteration`. All three protocols ultimately funnel into the same rule: the thing that gets awaited must be an awaitable, so a coroutine object or an `__await__` implementation. ### Failure modes Awaiting a non-awaitable produces a clear message - on 3.14, `TypeError: 'int' object can't be awaited` - and the most frequent real cause is awaiting the *result* of an already-awaited call, or awaiting a synchronous function's return value. The other classic is awaiting a coroutine *function* rather than calling it first: `await fetch` instead of `await fetch()`, which raises `TypeError: 'function' object can't be awaited`. ### When to reach for it Most application code never needs `__await__`. A coroutine function is shorter, reads better, and cannot be mis-driven, so the honest answer to "should I write a custom awaitable?" is usually no. The protocol earns its place in three narrow situations: an object that must be usable both as `await x` and in another style such as `async with x`; a bridge that turns a callback-registration API into something awaitable by yielding a future the callback later resolves; and low-level library code that needs to speak directly to the loop's driver. Each of those buys something a coroutine function cannot express. Everything else is complexity you will pay for at the next loop-framework change.