awaitables

Awaitables are objects that can be used with the await expression in asynchronous programming. In Python, an awaitable is any object that can be paused and resumed by an event loop until it yields a result. The typical kinds are coroutines (created by async def), Future objects, and Task objects, as well as any object that implements the __await__ method.

Mechanics: When an await expression is evaluated, the surrounding coroutine suspends and control returns to the event loop, which can run other tasks. The awaiting coroutine resumes once the awaitable completes, producing the result of the awaitable or propagating any exception. Awaiting a coroutine drives its execution; awaiting a Future or a Task yields the final result.

Creating and awaiting: A coroutine object is created by calling an async function. A Future represents a value that will be set later by some code. A Task wraps a coroutine for scheduling on the event loop. Any object with a __await__ method is considered awaitable.

Checking and utility: The inspect.isawaitable() function can be used to test if an object can be awaited. The __await__ method must return an iterator; this iterator defines how the object yields control back to the loop.

Notes: Awaitables are central to asynchronous programming in Python and are not limited to a single type. Understanding the distinction between coroutines, futures, and tasks helps design robust async code. In other languages, similar concepts exist under different names (for example, JavaScript promises with async/await).