leroyguillaume

python-async-conventions

leroyguillaume/claude/skills/python-async-conventions/SKILL.md

Python asyncio conventions for loops and fan-out — an `await` inside a `for` loop is sequential and usually a latency bug, but `asyncio.gather` is not a free swap: it drops short-circuiting, changes failure handling, and unbinds results from the items that produced them. Covers picking the axis to parallelise on, `gather` vs `TaskGroup`, bounding concurrency, and the tests that catch an over-eager fan-out. TRIGGER when: writing or editing an `async def` that loops; `await` appears inside a `for`/`while` body; calling the same coroutine once per item (per host, per file, per worker); introducing or reviewing `asyncio.gather`, `TaskGroup`, `as_completed`, `create_task` or a `Semaphore`; a fan-out or a batch; the user reports something slow, hanging, firing more requests than expected, or logging "Task exception was never retrieved". SKIP when: the code is synchronous, or the async code has no loop and no concurrency.