Async Context Managers and Async Generators

diagram async with and async for call different methods mermaid

  flowchart LR
  subgraph "async with"
    A["__aenter__ -- awaited"] --> B["body"]
    B --> C["__aexit__ -- awaited, runs on exceptions too"]
  end
  subgraph "async for"
    D["__aiter__"] --> E["__anext__ -- awaited each step"]
    E --> F["StopAsyncIteration ends the loop"]
  end
  G["a plain object"] -.->|"with obj:"| H["TypeError: does not support the context manager protocol"]
  I["contextlib.asynccontextmanager"] --> A

These are not the ordinary protocols with an await bolted on -- they are separate dunder methods, and an object supporting one does not support the other. That is why a synchronous context manager cannot be used with async with, and why an async generator cannot be driven by a plain for loop.

The observed order

text

__aenter__ , body , __aexit__ , gen start , got 0 , got 1 , gen end

__aenter__ and __aexit__ are awaited, so both may do I/O — opening a connection and closing it cleanly, which is the usual reason to write one. __aexit__ runs when the body raises as well, and returning a truthy value from it suppresses that exception.

Two mistakes worth naming:

A synchronous context manager will not work with async with. The method names are different entirely. Python 3.14 says so precisely:

text

TypeError: 'SyncCM' object does not support the asynchronous context manager
protocol (missed __aexit__ method) but it supports the context manager protocol.
Did you mean to use 'with'?

An async generator needs async for. A plain for over one gives TypeError: 'async_generator' object is not iterable, because __anext__ returns an awaitable rather than a value. The generator’s body does not begin until the first iteration, exactly like a synchronous generator.

Async context managers (async with)

You use async with when acquiring/releasing a resource needs await.

Common examples:

• aiohttp.ClientSession()
• async database connections
• async locks (asyncio.Lock)

Example: sessions and responses

aiohttp_context_manager.py

import asyncio
import aiohttp
 
 
async def main():
    async with aiohttp.ClientSession() as session:
        async with session.get("https://api.github.com") as resp:
            data = await resp.json()
            print(resp.status)
            print("keys:", list(data.keys())[:5])
 
 
asyncio.run(main())

Writing your own async context manager

Use @asynccontextmanager for a clean pattern.

custom_async_context_manager.py

import asyncio
from contextlib import asynccontextmanager
 
 
@asynccontextmanager
async def managed_resource(name: str):
    print("acquire", name)
    await asyncio.sleep(0.1)
    try:
        yield {"name": name}
    finally:
        print("release", name)
        await asyncio.sleep(0.1)
 
 
async def main():
    async with managed_resource("db-conn") as res:
        print(res)
 
 
asyncio.run(main())

Async generators (async def + yield)

An async generator is a generator that can await between yields.

It’s perfect for streaming data without loading everything into memory.

Example: async generator + async for

async_generator.py

import asyncio
 
 
async def ticker(n: int, delay: float = 0.2):
    for i in range(n):
        await asyncio.sleep(delay)
        yield i
 
 
async def main():
    async for value in ticker(5):
        print(value)
 
 
asyncio.run(main())

Important gotchas

• Use async with only with objects that implement __aenter__ / __aexit__.
• Use async for only on async iterables (implement __aiter__).
• Don’t forget to close async resources (sessions, connections). async with helps you avoid leaks.

sketch async with and async for use different methods entirely p5.js Pause Restart

These are not the ordinary protocols with an await bolted on. They are separate dunder methods, so an object supporting one does not support the other -- which is why a synchronous context manager fails under async with, and an async generator cannot be driven by a plain for loop. The order shown was observed from a real run.

Check yourself

pch.quizTag pch.quizDefaultTitle

1. Which methods does `async with` call?

   A `__enter__` and `__exit__`, awaited B `__aenter__` and `__aexit__` C `__await__` only D `__aiter__` and `__anext__`
   pch.quizShowAnswer

   B — `__aenter__` and `__aexit__` — They are separate dunder methods, not awaited versions of the sync ones. That is why a synchronous context manager cannot be used with `async with` at all.

2. You use `async with` on a class that defines `__enter__`/`__exit__`. What happens?

   A It works — Python adapts it B TypeError naming the missing `__aexit__`, and 3.14 suggests using `with` instead C It silently does nothing D It blocks the event loop
   pch.quizShowAnswer

   B — TypeError naming the missing `__aexit__`, and 3.14 suggests using `with` instead — Verified. The message reads: does not support the asynchronous context manager protocol (missed __aexit__ method) but it supports the context manager protocol. Did you mean to use 'with'?

3. Why is `__aexit__` worth having over an ordinary `finally`?

   A It runs faster B It is awaited, so cleanup can do I/O — closing a connection properly C It cannot be skipped D It suppresses all exceptions
   pch.quizShowAnswer

   B — It is awaited, so cleanup can do I/O — closing a connection properly — Both `__aenter__` and `__aexit__` are awaited, which is the usual reason to write one: acquiring and releasing something over the network.

4. A plain `for` loop over an async generator does what?

   A Works, but blocks B `TypeError: 'async_generator' object is not iterable` C Returns coroutines you must await D Runs only the first item
   pch.quizShowAnswer

   B — `TypeError: 'async_generator' object is not iterable` — `__anext__` returns an awaitable rather than a value, so the ordinary iteration protocol does not apply. Use `async for`.

🧪 Try It Yourself

Exercise 1 – Your First Coroutine

pch.exerciseTag pch.exerciseTitle

Exercise 2 – await asyncio.sleep

pch.exerciseTag pch.exerciseTitle

Exercise 3 – Gather Two Coroutines

pch.exerciseTag pch.exerciseTitle