Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 40 ยท Event Loop and Coroutines

Async Context Managers: async with

Learn async with, __aenter__ and __aexit__, contextlib.asynccontextmanager and AsyncExitStack to open and close connections and locks safely in asyncio.

Many resources need setup and cleanup that take time: opening a database connection, acquiring a lock, starting a transaction, connecting to a server. In normal Python the with statement guarantees cleanup. In asyncio, setup and cleanup can themselves require await, so Python provides the asynchronous context manager and the async with statement.

The protocol: __aenter__ and __aexit__

A class that defines async def __aenter__ and async def __aexit__ can be used with async with:

Python An async context manager class

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The order is: __aenter__ runs and its return value is bound to the name after as; the body runs; __aexit__ runs, even if the body raised. Returning a true value from __aexit__ would swallow the exception; normally return False (or None) so errors propagate.

Cleanup runs even on errors

The whole point is that cleanup is guaranteed. Here the body fails, and the connection still closes:

Python Cleanup on exceptions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

This commit-or-rollback shape is how async database libraries implement async with connection.transaction():.

@asynccontextmanager: the short way

Writing a class takes many lines. contextlib.asynccontextmanager turns an async generator with a single yield into a context manager. Code before yield is setup; code after it (inside finally) is cleanup:

Python asynccontextmanager

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Always wrap the yield in try/finally; otherwise an exception in the body would skip your cleanup. This decorator is the recommended style in modern code.

Context managers you already use

The standard library offers several async context managers:

  • asyncio.Lock, Semaphore, Condition: async with lock: acquires and releases (locks lesson).
  • asyncio.timeout(seconds): cancels the block if it takes too long.
  • asyncio.TaskGroup(): runs tasks together and waits for all of them (TaskGroup lesson).
  • Network libraries: aiohttp.ClientSession, httpx.AsyncClient, async database connections.

Here is asyncio.Lock used exactly like your own manager:

Python A lock is an async context manager

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Several managers and AsyncExitStack

Stack managers in one statement with commas:

Python
async with open_db() as db, open_cache() as cache:
    ...

When the number of managers is not known in advance, use contextlib.AsyncExitStack, which collects managers and closes them in reverse order:

Python AsyncExitStack

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Resources close in reverse order of opening: gamma, beta, alpha. This is the same last-in, first-out rule that with uses.

Common mistakes

  • Using plain with on an async manager raises TypeError ("does not support the context manager protocol"; it needs __enter__). Use async with.
  • Forgetting try/finally around yield in @asynccontextmanager, so cleanup is skipped on errors.
  • Blocking calls inside __aenter__/__aexit__, which freeze the loop; use awaitable operations.
  • Swallowing exceptions by accident with return True in __aexit__.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which two methods make a class usable with async with?

    async with calls the awaitable aenter and aexit methods.
  2. 2. In an @asynccontextmanager function, where should cleanup code go?

    Code after yield runs on exit, and a finally block guarantees it runs even if the body raised.
  3. 3. In which order does AsyncExitStack close the resources it manages?

    Last in, first out, exactly like nested with statements.
  4. 4. What happens if aexit returns True while the body raised ValueError?

    A true return value from aexit tells Python the exception was handled.

Summary

  • async with guarantees awaitable setup and cleanup via __aenter__ and __aexit__.
  • @asynccontextmanager builds one from an async generator; put cleanup in finally.
  • Locks, timeouts, task groups, HTTP clients and DB connections are all async context managers.
  • AsyncExitStack manages a dynamic number of them and closes them in reverse order.

Next: Blocking the event loop