asyncio.shield(my_coro())

Concurrency & Async

Meaning

asyncio.shield wraps a coroutine so that it is protected from cancellation; if the surrounding task is cancelled, the shielded coroutine continues to run until completion, and its result or exception is propagated.

Primary Function

Concurrency control / Task management

Communicative Purpose

Prevent a coroutine from being cancelled when the outer task is cancelled.

Pattern

asyncio.shield(coro())

Core Structure

asyncio.shield(...)

Função primária

Concurrency control / Task management

Propósito comunicativo

Prevent a coroutine from being cancelled when the outer task is cancelled.

Situações de gatilho

Asyncio: Performing cleanup operations that must finish even on cancellation. Asyncio: Sending a final response or closing resources reliably. Asyncio: Running a critical section that should not be aborted mid‑execution.

Contextos

Asyncio‑based applications such as web servers, background workers, and any code using asyncio for cooperative multitasking.

Padrão

asyncio.shield(coro())

Estrutura central

asyncio.shield(...)

Slots de substituição

coro: a call that returns a coroutine object (e.g., an async function call).

Colocados típicos

await
asyncio.create_task
asyncio.gather
try/except
async with

Substituições comuns

asyncio.wait_for (with timeout)
manual try/except catching asyncio.CancelledError.

Erros comuns

Forgetting to await the shielded task, assuming shield suppresses exceptions, applying shield to a non‑coroutine object.

Similar / contraste

asyncio.wait_for – adds a timeout and can cancel the wrapped coroutine; asyncio.create_task – schedules a coroutine without cancellation protection.

Interferências

Coming from threading: may think shield is equivalent to setting a thread as daemon — shield only guards against asyncio cancellation, not against exceptions or internal cancellation handling.

Família do chunk

asyncio.create_task
asyncio.gather
asyncio.wait_for

Nuance

Shield only protects against cancellation; if the coroutine raises an exception (including CancelledError caught inside), it propagates normally. The returned Task must be awaited; otherwise it may be cancelled later or raise a warning about unawaited task.

Efeito pragmático

Guarantees that critical cleanup or finalization code runs to completion even when the surrounding task is cancelled.

Dica de memória

Think of a shield blocking cancellation arrows – the coroutine keeps going despite outer cancel signals.

Nota

Shield does not prevent the coroutine from catching and acting on asyncio.CancelledError internally; if the coroutine suppresses CancelledError, shield cannot force it to respect cancellation.

Upgrade path

Use asyncio.wait_for(timeout) when you need both cancellation protection and a timeout, or build a custom wrapper that logs before shielding.

Frequência: MediumFormulaicidade: Semi-fixedTipo de construção: higher-order function call (wrapper)Prioridade de aquisição: Recognition firstPrioridade de output: BothTag de espaçamento: Medium-term

Examples

import asyncio async def slow_job(): await asyncio.sleep(2) return 'done' async def main(): task = asyncio.shield(slow_job()) result = await task print(result) asyncio.run(main())

import asyncio async def finalize_payment(): await asyncio.sleep(2) print("Payment finalized") async def process_order(): shielded = asyncio.shield(finalize_payment()) try: await shielded except asyncio.CancelledError: print("Order cancelled, but payment still finalizes") raise async def main(): task = asyncio.create_task(process_order()) await asyncio.sleep(0.5) task.cancel() try: await task except asyncio.CancelledError: pass await asyncio.sleep(2.5) asyncio.run(main())

import asyncio async def job(n): await asyncio.sleep(n) return f'job-{n} done' async def main(): # shield each job so gather won't cancel them if one fails shielded = [asyncio.shield(job(i)) for i in range(1, 4)] results = await asyncio.gather(*shielded, return_exceptions=True) print(results) asyncio.run(main())