Meaning
Assigns the return value of an awaited coroutine or awaitable to a local variable, suspending the enclosing coroutine until the awaitable completes. Addresses the pain point of needing the concrete result of an asynchronous operation before proceeding with dependent logic. Triggered whenever an async function must use the outcome of another async call rather than fire-and-forget.
Primary Function
Asynchronous execution
Communicative Purpose
Enables suspending the current coroutine until an awaitable finishes and capturing its return value for subsequent logic.
Pattern
result = await awaitable
Core Structure
... = await ...
Função primária
Asynchronous execution
Propósito comunicativo
Enables suspending the current coroutine until an awaitable finishes and capturing its return value for subsequent logic.
Situações de gatilho
Web services: awaiting a database query result before rendering a response. File I/O: awaiting async file reads to obtain file contents for processing. Network clients: awaiting an HTTP response to inspect status and body.
Contextos
Inside an async def function; after calling an async function, method returning a coroutine, or when you have a Future/Task ready to be awaited.
Padrão
result = await awaitable
Estrutura central
... = await ...
Slots de substituição
result: any valid Python identifier, awaitable: any expression yielding an awaitable (coroutine, Future, Task)
Colocados típicos
- async def
- await
- coroutine
- Future
- Task
- asyncio
Substituições comuns
- Variable name can be any identifier
- awaitable can be a function call
- method call
- attribute access
- or a variable holding an awaitable.
Erros comuns
Forgetting to await (cause: treating async function like a sync one; consequence: variable holds a coroutine object, not the result, leading to subtle bugs). Using await outside an async def (cause: misunderstanding async scope; consequence: SyntaxError at import time). Awaiting a non-awaitable like a plain int (cause: passing wrong type; consequence: TypeError at runtime). Awaiting the same coroutine twice (cause: not realizing coroutines are one-shot; consequence: RuntimeError on second await).
Similar / contraste
asyncio.create_task(): schedules concurrent execution without waiting. asyncio.gather(): awaits multiple awaitables in parallel. yield from: delegates to a sub-generator in synchronous generator context.
Interferências
Coming from JavaScript: may assume await works at module top-level — Python requires await inside an async def or event loop entry point. Coming from synchronous Python: may call an async function without await, which returns a coroutine object instead of the actual result.
Família do chunk
- async-await-pattern
Nuance
Do not use await when you want concurrent execution — use asyncio.create_task() instead and await the task later. Each await is a suspension point that yields control to the event loop, so excessive sequential awaits serialize what should be parallel. Awaiting a coroutine object directly runs it immediately on the current event loop; it is not pre-scheduled.
Efeito pragmático
Signals a suspension point and the retrieval of an asynchronous result, indicating reliance on the outcome of the awaitable.
Dica de memória
Like placing a phone call on hold — you suspend what you're doing until the other party finishes, then pick up exactly where you left off with their answer in hand.
Nota
Must appear inside an async def function; otherwise a SyntaxError is raised.
Upgrade path
Consider using asyncio.create_task() for fire‑and‑forget or asyncio.gather() for awaiting multiple awaitables.
Log in to save chunks.