async-python-patterns

async-python-patterns

Decision framework for picking the right Python asyncio primitive. The pattern cookbook lives upstream (links in § Provenance) — this skill is the predicate, not the recipe library. Sunset-policy compliant: the 600+ lines of language-specific cookbook stay in authoritative Python docs.

When to use

• Designing a new async I/O-bound service (FastAPI, aiohttp, async DB client).
• Reviewing a diff that introduces asyncio.gather, asyncio.create_task, TaskGroup, as_completed, or wait_for.
• Mixing sync and async code (calling sync libs from async context, or vice versa).
• Diagnosing event-loop blocking, never-awaited warnings, or cancellation leaks.

Do NOT use when:

• The work is CPU-bound — async will not help; route to multiprocessing or threadpool.
• The runtime is not Python — read the host runtime's concurrency guide.
• The fix is a single missing await — read the upstream tutorial directly.

Decision framework

Step 1 — Verify async is the right tool

Workload is:
  I/O-bound, many concurrent waits  → async fits (network, disk, IPC).
  CPU-bound (parsing, math, crypto) → async is wrong; use ProcessPoolExecutor.
  Mixed                              → async shell + run_in_executor for CPU bursts.
  Single sequential call             → don't introduce async; sync is simpler.

Step 2 — Pick the concurrency primitive

Run N independent coroutines, ALL must complete:
  Same trust level, exceptions cancel siblings  → asyncio.TaskGroup (3.11+; preferred).
  Pre-3.11 OR exceptions must NOT cancel peers  → asyncio.gather(*, return_exceptions=...).

Run N coroutines, react to results as they finish:
  → asyncio.as_completed (yields completed futures in finish order).

Run N coroutines, race to first success / failure:
  → asyncio.wait(..., return_when=FIRST_COMPLETED) + cancel pending.

Schedule fire-and-forget background work:
  → asyncio.create_task + keep a strong reference (else GC eats it).
  Forgetting the reference is the #1 silent-failure source.

Bound the wait time:
  → asyncio.wait_for(coro, timeout=...)  → raises TimeoutError on expiry.
  → asyncio.timeout(...) context manager (3.11+; preferred when many awaits share a deadline).

Bound concurrency (rate-limit, connection pool):
  → asyncio.Semaphore(n); acquire around the awaitable.