Python Asynchronous Context Managers

Intermediate

An asynchronous context manager controls a runtime context when entering or leaving may need to suspend. Python uses async with for this form of resource or state management. The protocol is built around __aenter__() and __aexit__(), which return awaitables.

async with enters and exits an asynchronous context

An async with statement is the asynchronous counterpart to with. It evaluates the context manager, awaits __aenter__(), runs the block, and later awaits __aexit__(). The optional as target receives the value produced by __aenter__().

Entry and exit can suspend

The point of the asynchronous protocol is that entering and leaving the context can await other asynchronous work. An async def __aenter__() returns a coroutine, so async with awaits it before the block starts. An async def __aexit__() likewise returns a coroutine that async with awaits during cleanup.

as receives the awaited entry value

In async with Manager() as value, the name value does not receive an unawaited coroutine. Python awaits __aenter__() first, and the resulting value is assigned to the as target.

__aexit__ still runs when the block raises

After a successful __aenter__(), Python awaits __aexit__() when the async with block finishes. If the block raises, the exception type, value, and traceback are supplied to __aexit__(). Returning a false value allows the exception to propagate.

__aexit__ can suppress an exception

As with ordinary context managers, an asynchronous __aexit__() can suppress an exception by returning a true value. Suppression should be deliberate because it changes normal exception propagation.

Multiple asynchronous contexts nest

You can place multiple context-manager items in one async with statement. Python processes them like nested async with statements, so contexts enter from left to right and exit in reverse order.

async with belongs inside a coroutine

The async with statement is asynchronous syntax, so Python only permits it in the body of a coroutine function. At the top level of a normal module, it is a SyntaxError.

async with needs the asynchronous protocol

A normal context manager that only defines __enter__() and __exit__() is not automatically an asynchronous context manager. async with looks for __aenter__() and __aexit__(). This keeps synchronous cleanup and asynchronous cleanup as distinct protocols.

Quick check

class Manager:
    ?

    async def __aexit__(self, exc_type, exc_value, traceback):
        return False