async-patterns.md

id	python-async-patterns
type	guide
title	Reliable Async Python Patterns and Pitfalls
summary	Build resilient concurrent Python applications by avoiding common async antipatterns and managing task lifecycles.
lang	en-US
content_version	1
status	reviewed
reviewed_on	2026-09-02

Reliable Async Python Patterns and Pitfalls

Asynchronous Python (asyncio) offers high throughput for IO-bound applications, such as web services built with FastAPI documentation or batch pipelines using HTTPX documentation. However, AI coding agents frequently introduce subtle concurrency bugs.

1. Never invoke blocking IO inside the event loop

Calling synchronous filesystem or network methods (such as time.sleep or standard sync file reads) blocks the entire event loop, starving other concurrent coroutines. Offload unavoidable blocking operations to worker threads via asyncio.to_thread():

import asyncio

def blocking_io_task(): ...

async def handle_request():
    result = await asyncio.to_thread(blocking_io_task)

2. Prefer TaskGroup over bare gather

In Python 3.11+, use asyncio.TaskGroup for structured concurrency instead of asyncio.gather. TaskGroup guarantees that if any child task raises an unhandled exception, all sibling tasks are immediately cancelled and cleaned up, preventing orphan runaway tasks.

import asyncio

async def main():
    async with asyncio.TaskGroup() as tg:
        task1 = tg.create_task(fetch_user(1))
        task2 = tg.create_task(fetch_orders(1))

3. Bound concurrency with Semaphore

Never launch unbounded coroutines on large datasets. Always wrap concurrent operations in an asyncio.Semaphore to cap open file descriptors and avoid rate-limiting triggers.

4. Handle cancellation and cleanup

Always use try...finally blocks or async context managers to release database connections, network sessions, and lock resources when an async operation is cancelled.