Timeouts and shielding: scoped cancel with TimeoutError conversion, deadline propagation, and shield as half a tool

asyncio.timeout is a scoped cancel, not a stopwatch

When you reach for a timeout, ask yourself: do you want to bound when the work ends, or who may interrupt it? The answer decides whether you need asyncio.timeout, shield, or both — and confusing them is how a shielded flush becomes an unbounded hostage. async with asyncio.timeout(5): (3.11+) does three things you can now name precisely from lessons 1 and 2. It schedules a call_at timer on the loop heap; at expiry, that timer cancels the current task — an ordinary injected CancelledError, landing at the body’s next suspension point; and at the scope’s exit, if the arriving CancelledError was its own doing, it converts it to TimeoutError. Outside the scope you see a clean timeout; inside, the body experienced plain cancellation — so all of lesson 2 applies verbatim inside a timeout scope: finally blocks run, cleanup must be bounded, swallowing breaks everything.

The conversion decision is the deep part: how does the scope know the cancellation was its own? Cancel-count bookkeeping. Each cancel() increments the task’s cancelling count; when the scope’s timer fired the cancel, the scope calls uncancel() on exit — if the count drops back to zero, the cancellation belonged to this scope and becomes TimeoutError; if it stays positive, an outer cancellation (or outer timeout) is also in flight, and the scope re-raises CancelledError untouched so the outer claim wins. This is what makes nesting compose:

async with asyncio.timeout(10):        # outer budget
    async with asyncio.timeout(2):     # inner, stricter
        await fetch()                  # takes 5 s
# inner scope: its timer fired, its uncancel() zeroes the count -> TimeoutError
# outer scope: never fired, sees an ordinary exception fly through, stays armed

wait_for is the older sibling: it wraps a single awaitable (creating a Task for a bare coroutine), where timeout() scopes a block. Historically wait_for had real edge cases around the result-arrives-while-cancelling race — completed work could be dropped, or cancellation leaked; since 3.12 it is reimplemented on top of asyncio.timeout, inheriting the count bookkeeping. Modern code prefers the scope: it composes, it covers multiple awaits, and it does not force a Task allocation.

Deadlines travel; timeouts do not

A constant per-hop timeout is the junior version of the idea. A request that must answer in 2 s and makes three sequential downstream calls cannot give each call 2 s — the budgets must share the deadline, each hop computing the remainder. This is the same pattern Go institutionalizes as context deadlines (the go track’s context-discipline lesson); in asyncio you carry a deadline and derive scopes from it — asyncio.timeout_at(when) takes an absolute loop-clock time for exactly this:

async def call_with_deadline(deadline, op):
    loop = asyncio.get_running_loop()
    if deadline - loop.time() <= 0:
        raise TimeoutError("budget exhausted before the call")
    async with asyncio.timeout_at(deadline):   # absolute, shared, shrinking
        return await op()

async def handler():
    deadline = asyncio.get_running_loop().time() + 2.0   # client-facing budget
    user = await call_with_deadline(deadline, fetch_user)
    orders = await call_with_deadline(deadline, fetch_orders)  # gets the REMAINDER
    return render(user, orders)

The classic misordering incident: an outer timeout(5) around a retry loop whose per-attempt budget is 10 s with three attempts. The outer scope always fires mid-attempt-one; the per-attempt timeout never trips; the retry loop is unreachable code wearing a straight face — metrics show retries == 0 forever while the postmortem assumed three attempts. The rule worth pinning: budgets must nest strictly — per-attempt under per-request under client-facing — and the only structure that enforces it automatically is deriving every inner scope from one shrinking deadline.

shield: who may not interrupt — not how long

asyncio.shield(thing) wraps the awaitable in a Task and gives you a guarded await on it. When outer cancellation arrives, it hits the shield wait, not the inner task: your await shield(...) raises CancelledError immediately, while the inner task keeps running, detached. That sentence contains both the feature and the failure mode. The feature: a commit already in flight, a write-behind cache flush — work whose abandonment costs more than its completion — survives the cancellation storm around it. The failure mode is the orphan problem: after the shield wait dies, who awaits the inner task? If you did not keep a reference, its result and its exceptions vanish into the task graveyard (and “Task exception was never retrieved” logs at best). And the Hook is the second failure: shield bounds interruption, not duration — shielded work awaiting a dead peer runs forever. The pair is the discipline:

async def flush_on_shutdown(exporter):
    flush = asyncio.ensure_future(exporter.flush())   # named: no orphan
    try:
        await asyncio.shield(flush)                   # outer cancel stops HERE
    except asyncio.CancelledError:
        async with asyncio.timeout(5):                # bound the protected work
            await flush                               # let it finish - or not
        raise                                         # then honor the cancel

Shielding everything is the abuse pattern: a service whose handlers all shield their bodies is simply unkillable — cancellation, timeouts, and graceful shutdown all degrade to SIGKILL. Shield is for the narrow class of must-complete work, always with a bound, always with a kept reference.