Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 40 ยท Timeouts and Cancellation

Timeouts with wait_for and asyncio.timeout

Put deadlines on async code: asyncio.timeout(), timeout_at(), wait_for(), wait() and as_completed() with timeouts, rescheduling, nesting and common mistakes.

Anything that waits on the outside world can wait forever: a server that never replies, a lock nobody releases, a queue that stays empty. A program that never gives up is a program that hangs in production. asyncio gives you several ways to say "stop waiting after this long", and all of them work the same way underneath: when the time is up, the waiting task is cancelled.

This lesson covers the modern tool, the asyncio.timeout() context manager, the older asyncio.wait_for(), and the timeout options of asyncio.wait() and as_completed(). Cancellation itself is the subject of the next lesson.

asyncio.timeout(): a deadline for a block

asyncio.timeout(seconds) is an async context manager (Python 3.11 and later). Everything awaited inside the async with block shares one deadline.

Python A deadline for a block

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Two things are worth understanding here:

  1. The deadline covers the whole block, not each call. The first fetch used a little of the 0.3 s budget; the second got only what was left.
  2. The TimeoutError is raised when the async with block exits, not inside the awaited code. Inside, the slow await receives a CancelledError, which unwinds your finally blocks and context managers. At the exit, asyncio converts it into the built-in TimeoutError. So always put the try/except TimeoutError outside the async with.

TimeoutError is the ordinary built-in exception (from Python 3.11, asyncio.TimeoutError is just an alias for it), so a single except TimeoutError catches both asyncio and socket timeouts.

Inspecting and moving the deadline

The object returned by async with asyncio.timeout(...) as cm lets you check and change the deadline:

  • cm.expired() is true if the timeout fired.
  • cm.when() gives the absolute deadline on the loop's clock (or None).
  • cm.reschedule(when) moves it. Pass None to remove the deadline.

asyncio.timeout(None) starts with no deadline, handy when the limit is optional or decided later. asyncio.timeout_at(when) takes an absolute time from loop.time() instead of a duration.

Python timeout_at, reschedule and nesting

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

wait_for(): a deadline for one awaitable

await asyncio.wait_for(awaitable, timeout) runs one awaitable and raises TimeoutError if it takes longer. It is a good fit when you wrap a single call.

Python
try:
    result = await asyncio.wait_for(fetch_user(42), timeout=2.0)
except TimeoutError:
    result = None

When the time runs out, wait_for cancels the inner awaitable and waits for the cancellation to finish before raising, so by the time you see the exception nothing is still running. Passing timeout=None waits without limit. In new code, prefer asyncio.timeout(): it works with several awaits in a row, it does not wrap the call in a new task, and the code reads more naturally. wait_for is still perfectly fine for one-liners.

asyncio.wait() with a timeout: do not cancel, just stop waiting

asyncio.wait(tasks, timeout=...) behaves differently. It does not raise and it does not cancel anything: it returns two sets, the tasks that are done and those still pending. What to do with the pending ones is up to you.

Python wait() returns done and pending

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Use wait() when partial results are acceptable ("show whichever search backends answered within 200 ms"), and timeout() when the whole operation is useless without all of it.

Choosing a timeout value

  • Set connect and read timeouts separately when you can; a network call that is slow to start is different from one that stalls midway.
  • Timeouts must be longer than the 99th percentile of the normal case, or they will trigger retries that make the overload worse. See retries and backoff.
  • A timeout that surrounds many steps (a whole request handler) protects you from the sum of many small waits.
  • Remember that timeouts only interrupt code at an await. A loop doing pure computation with no await cannot be interrupted at all; the timer fires late, after the computation ends.

A timeout cannot stop blocking code. time.sleep(5) or a long CPU loop inside a coroutine holds the whole event loop. The timeout callback cannot even run until the loop is free again. Move blocking work out of the loop with to_thread instead.

Common mistakes

  • Catching TimeoutError inside the async with asyncio.timeout() block. It is raised at the exit; the code inside only sees CancelledError.
  • Swallowing CancelledError in a try/except Exception that is too broad (it is not an Exception subclass, but except BaseException: or a bare except: catches it). The timeout then never takes effect.
  • Forgetting that wait_for on a coroutine creates a task, while timeout() leaves the code in your own task, which matters for context variables and task-local state.
  • Using timeouts as the only defence against an unbounded queue or runaway producer. Use backpressure too.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where must the try/except TimeoutError go when you use "async with asyncio.timeout(1):"?

    The awaited code inside receives CancelledError. The TimeoutError is raised when the async with block exits, so the handler must surround it.
  2. 2. What does asyncio.wait(tasks, timeout=1) do when some tasks are still running after one second?

    wait() never raises for a timeout and never cancels. You decide what to do with the pending set.
  3. 3. You have three sequential awaits that together must finish in 2 seconds. Which is the cleanest tool?

    One shared deadline over the whole block is exactly what asyncio.timeout() provides.
  4. 4. Why can a timeout fail to interrupt "total = sum(range(10**9))" inside a coroutine?

    Cancellation takes effect at an await. A long computation without awaits blocks the loop entirely.

Summary

  • async with asyncio.timeout(s) puts one deadline on a whole block; timeout_at(when) uses an absolute loop time; reschedule() changes it.
  • On expiry the inner code is cancelled and a TimeoutError appears when the block exits, so catch it outside.
  • wait_for() suits a single awaitable; wait(..., timeout=) and as_completed(..., timeout=) give partial results without cancelling.
  • Timeouts only work at await points and never interrupt blocking code.

Next: Cancelling tasks