Introduction
Regular context managers (with) work for sync code. But in async code — where you await I/O operations — you need async context managers (async with). They guarantee cleanup (closing connections, releasing locks) even when coroutines are cancelled or exceptions occur.
The problem
# Sync context manager — blocks the event loop
with open("file.txt") as f:
data = f.read() # blocking I/O in async code!
# Async context manager — non-blocking
async with aiofiles.open("file.txt") as f:
data = await f.read() # non-blocking
Using sync context managers inside async code blocks the entire event loop.
The protocol: __aenter__ and __aexit__
class AsyncManagedResource:
async def __aenter__(self):
self.conn = await create_connection()
return self.conn
async def __aexit__(self, exc_type, exc_val, exc_tb):
await self.conn.close()
return False # don't suppress exceptions
async def main():
async with AsyncManagedResource() as conn:
data = await conn.fetch("SELECT 1")
# conn is closed here
__aenter__ and __aexit__ are coroutines — they’re awaited by the async with statement.
@asynccontextmanager (the easy way)
from contextlib import asynccontextmanager
@asynccontextmanager
async def managed_connection():
conn = await create_connection()
try:
yield conn
finally:
await conn.close()
async def main():
async with managed_connection() as conn:
data = await conn.fetch("SELECT 1")
Same pattern as sync @contextmanager, but with async def and await.
Real-world examples
1. HTTP session (aiohttp)
import aiohttp
async def fetch_all(urls):
async with aiohttp.ClientSession() as session:
tasks = [fetch(session, url) for url in urls]
return await asyncio.gather(*tasks)
ClientSession manages connection pooling — async with ensures it’s closed properly.
2. Database connection (asyncpg)
import asyncpg
@asynccontextmanager
async def get_db():
conn = await asyncpg.connect("postgresql://user:pass@localhost/db")
try:
yield conn
finally:
await conn.close()
async def get_user(user_id):
async with get_db() as conn:
return await conn.fetchrow("SELECT * FROM users WHERE id = $1", user_id)
3. Redis connection (aioredis)
import redis.asyncio as aioredis
@asynccontextmanager
async def get_redis():
r = aioredis.from_url("redis://localhost")
try:
yield r
finally:
await r.close()
async def cache_get(key):
async with get_redis() as r:
return await r.get(key)
4. Lock
import asyncio
lock = asyncio.Lock()
async def critical_section():
async with lock:
# only one coroutine at a time
await do_work()
5. Semaphore (rate limiting)
sem = asyncio.Semaphore(5)
async def fetch_limited(url):
async with sem:
return await fetch(url)
AsyncExitStack (dynamic)
For a variable number of async context managers:
from contextlib import AsyncExitStack
async def process_files(paths):
async with AsyncExitStack() as stack:
files = [await stack.enter_async_context(aiofiles.open(p)) for p in paths]
for f in files:
data = await f.read()
process(data)
Combining sync and async
Sometimes you need both sync and async cleanup:
from contextlib import asynccontextmanager
@asynccontextmanager
async def hybrid_resource():
# Sync setup
sync_resource = open("file.txt")
# Async setup
async_resource = await create_async_conn()
try:
yield sync_resource, async_resource
finally:
# Async cleanup
await async_resource.close()
# Sync cleanup
sync_resource.close()
Common mistakes
- Using sync
within async code — blocks the event loop. Useasync with. - Forgetting
awaiton__aenter__/__aexit__— they’re coroutines. - Not using
try/finally— exceptions skip cleanup without it. - Mixing sync and async context managers —
withfor sync,async withfor async. Don’t mix. - Returning True from
__aexit__— suppresses exceptions silently. Only do this intentionally.
Key Concepts
async with= async version ofwith__aenter__/__aexit__= async protocol methods@asynccontextmanager= decorator for async context managersAsyncExitStack= manage dynamic async context managers- Cleanup guarantee =
__aexit__runs even on exceptions/cancellation
What to Try Next
- Wrap your DB connections in async context managers.
- Use async context managers in your web scraper.
- Combine with asyncio for concurrent I/O.
- Add async context managers to your FastAPI backend.
FAQ
async with vs with — when to use which?
Use async with when the resource’s setup/teardown involves I/O (DB connections, HTTP sessions, file I/O in async code). Use with for sync resources (files in sync code, locks, etc.).
Can I use sync context managers in async code?
Yes, but they block the event loop during setup/teardown. For file I/O, use aiofiles. For DB, use async drivers. For quick operations, asyncio.to_thread() wraps sync code.
asynccontextmanager vs class-based — which to use?
@asynccontextmanager is simpler and covers 90% of cases. Use class-based when you need complex state, multiple methods, or reusable objects. Prefer the decorator for simplicity.