Async python patterns
Skill event4u-app/agent-config/src/skills/async-python-patterns
Use when writing Python asyncio code — picking between gather / TaskGroup / wait, structured concurrency, timeouts, cancellation, sync-bridging — decision framework only, cookbook externalized.From its SKILL.md
npx -y skills add event4u-app/agent-config --skill async-python-patternsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 19 stars19 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
8.0 KB, ~1.7k tokens by cl100k_base, as published. Nobody here has run it
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, orwait_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.
Step 3 — Bridge sync ↔ async correctly
Async code calls sync, blocking, function:
Short pure-CPU → fine, accept the block (microseconds).
Long, blocking, or I/O-sync → await loop.run_in_executor(None, fn, *args).
Library has async sibling → switch the library (httpx vs requests, aiosqlite vs sqlite3).
Sync code calls async function:
Top-level entrypoint → asyncio.run(coro()).
Inside running loop → never asyncio.run; create_task + await it.
Test suite → pytest-asyncio fixture; never raw run() in tests.
Step 4 — Cancellation discipline
Every long-running coroutine MUST be cancellation-safe:
- Catch
asyncio.CancelledError, perform cleanup, re-raise. Swallowing it silently breaks the propagation chain. - Use
try / finally(orasync with) around resource acquisition so cancellation cannot leak file handles, DB connections, locks. - Detached
create_taskwithout a strong reference is undefined behavior; either store the task or use a TaskGroup.
Step 5 — Don't block the event loop
A single blocking call (sync I/O, time.sleep, CPU-heavy parse, large JSON load) freezes every coroutine. Audit every leaf function under async def:
- Sleep →
await asyncio.sleep, nevertime.sleep. - HTTP →
httpx.AsyncClient/aiohttp, neverrequests. - DB →
asyncpg/aiosqlite/motor, never the sync driver. - File →
aiofilesfor hot-paths, orrun_in_executorfor one-shots.
Procedure: Apply to a new async feature
- Inspect the existing call graph and identify each
awaitsite, sync↔async boundary, and any blocking leaf calls before touching code. - Run Step 1; reject if work is CPU-bound.
- Sketch the call graph; tag each
awaitsite with its primitive (Step 2). - Mark every sync↔async boundary; pick the bridge per Step 3.
- For each long-running coroutine, write the cancel-safety contract (Step 4).
- Grep the leaf calls for blocking sins (Step 5); replace or push to executor.
- Hand the sketch to a reviewer before coding; cite this skill.
Output format
- Call-graph table: coroutine · concurrency primitive · timeout · cancel-safety note.
- Sync↔async boundary list: site · bridge · justification.
- Blocking-call audit: leaf function · status (async / executor / accepted-block + reason).
- Cancel-safety contract for each background task.
Gotcha
- "It works in my REPL" —
asyncio.runinside an already-running loop (Jupyter, FastAPI startup) raisesRuntimeError. Useawaitdirectly ornest_asyncio(last resort). asyncio.gatherswallows the second exception silently; usereturn_exceptions=Trueand inspect, or useTaskGroup(cancels all on first error, surfaces the group).create_taskresults that nobody awaits look fine until the program exits and Python printsTask was destroyed but it is pending!. Alwaysawaitor use a TaskGroup.wait_foron a non-cancellation-safe coroutine leaks resources; the timeout cancels the task but cleanup never runs.- Libraries that "support async" via thread pools (e.g.
requests-async) often re-block the loop under load; verify with the cited upstream library docs, not the README.
Do NOT
- Do NOT call
asyncio.runfrom a running loop. - Do NOT swallow
CancelledErrorwithout re-raising. - Do NOT call sync blocking I/O from async paths without
run_in_executor. - Do NOT spawn
create_taskwithout storing the reference (or using TaskGroup). - Do NOT inline the asyncio cookbook into this skill — externalize per Sunset Policy.
Auto-trigger keywords
- asyncio
- async / await
- gather / TaskGroup / wait_for
- event loop blocking
- cancellation
- sync to async bridge
Provenance
- Adopted from: an external reference (internal provenance, redacted) — Sunset Policy applied: a large cookbook source reduced to a ~140-line decision framework; pattern catalogues externalized to upstream docs below.
- Externalized cookbook:
- asyncio core: https://docs.python.org/3/library/asyncio.html · https://docs.python.org/3/library/asyncio-task.html
- TaskGroup (3.11+): https://docs.python.org/3/library/asyncio-task.html#task-groups
- Structured concurrency: https://anyio.readthedocs.io · https://trio.readthedocs.io
- Async HTTP: https://www.python-httpx.org/async/ · https://docs.aiohttp.org/en/stable/
- Async DB: https://magicstack.github.io/asyncpg/ · https://aiosqlite.omnilib.dev/
- Cross-linked:
error-handling-patterns,mcp-builder,api-design,performance. - Provenance registry:
agents/settings/contexts/skills-provenance.yml(entry:async-python-patterns). - Iron-Law floor:
verify-before-complete,skill-quality,non-destructive-by-default.
What ships with it
Read from the repository
Just SKILL.md. No reference files, no scripts.