Abstract

Python allows the with and async with statements to handle multiple context managers in a single statement, so long as they are all respectively synchronous or asynchronous. When mixing synchronous and asynchronous context managers, developers must use deeply nested statements or use risky workarounds such as overuse of AsyncExitStack.

We therefore propose to allow with statements to accept both synchronous and asynchronous context managers in a single statement by prefixing individual async context managers with the async keyword.

This change eliminates unnecessary nesting, improves code readability, and improves ergonomics without making async code any less explicit.

Motivation

Modern Python applications frequently need to acquire multiple resources, via a mixture of synchronous and asynchronous context managers. While the all-sync or all-async cases permit a single statement with multiple context managers, mixing the two results in the “staircase of doom”:

async def process_data():
    async with acquire_lock() as lock:
        with temp_directory() as tmpdir:
            async with connect_to_db(cache=tmpdir) as db:
                with open('config.json', encoding='utf-8') as f:
                    # We're now 16 spaces deep before any actual logic
                    config = json.load(f)
                    await db.execute(config['query'])
                    # ... more processing

This excessive indentation discourages use of context managers, despite their desirable semantics. See the Rejected Ideas section for current workarounds and commentary on their downsides.

With this PEP, the function could instead be written:

async def process_data():
    with (
        async acquire_lock() as lock,
        temp_directory() as tmpdir,
        async connect_to_db(cache=tmpdir) as db,
        open('config.json', encoding='utf-8') as f,
    ):
        config = json.load(f)
        await db.execute(config['query'])
        # ... more processing

This compact alternative avoids forcing a new level of indentation on every switch between sync and async context managers. At the same time, it uses only existing keywords, distinguishing async code with the async keyword more precisely even than our current syntax.

We do not propose that the async with statement should ever be deprecated, and indeed advocate its continued use for single-line statements so that “async” is the first non-whitespace token of each line opening an async context manager.

Our proposal nonetheless permits with async some_ctx(), valuing consistent syntax design over enforcement of a single code style which we expect will be handled by style guides, linters, formatters, etc. See here for further discussion.

Rationale

Mixed sync/async context managers are common in modern Python applications, such as async database connections or API clients and synchronous file operations. The current syntax forces developers to choose between deeply nested code or error-prone workarounds like AsyncExitStack.

This PEP addresses the problem with a minimal syntax change that builds on existing patterns. By allowing individual context managers to be marked with async, we maintain Python’s explicit approach to asynchronous code while eliminating unnecessary nesting.

The implementation as syntactic sugar ensures zero runtime overhead – the new syntax desugars to the same nested with and async with statements developers write today. This approach requires no new protocols, no changes to existing context managers, and no new runtime behaviors to understand.

Specification

The with (..., async ...): syntax desugars into a sequence of context managers in the same way as current multi-context with statements, except that those prefixed by the async keyword use the __aenter__ / __aexit__ protocol.

Only the with statement is modified; async with async ctx(): is a syntax error.

The ast.withitem node gains a new is_async integer attribute, following the existing is_async attribute on ast.comprehension. For async with statement items, this attribute is always 1. For items in a regular with statement, the attribute is 1 when the async keyword is present and 0 otherwise. This allows the AST to precisely represent which context managers should use the async protocol while maintaining backwards compatibility with existing AST processing tools.

Backwards Compatibility

This change is fully backwards compatible: the only observable difference is that certain syntax that previously raised SyntaxError now executes successfully.

Libraries that implement context managers (standard library and third-party) work with the new syntax without modifications. Libraries and tools which work directly with source code will need minor updates, as for any new syntax.

How to Teach This

We recommend introducing “mixed context managers” together with or immediately after async with. For example, a tutorial might cover:

1. Basic context managers: Start with single with statements
2. Multiple context managers: Show the current comma syntax
3. Async context managers: Introduce async with
4. Mixed contexts: “Mark each async context manager with async”

Rejected Ideas

@contextmanager
async def as_acm(sync_cm):
    with sync_cm as result:
        await sleep(0)
        yield result

async with (
    acquire_lock(),
    as_acm(open('file')) as f,
):
    ...

async with contextlib.AsyncExitStack() as stack:
    await stack.enter_async_context(acquire_lock())
    f = stack.enter_context(open('file', encoding='utf-8'))
    ...

async with multicontext(
    acquire_lock(),
    open('file'),
) as (f, _):
    ...

# Rejected approach
async with (
    acquire_lock(),
    open('config.json') as f,  # actually sync, surprise!
):
    ...

with (
    sync_context() as foo,
    async a_context() as bar,
): ...

with (
    sync_context() as foo,
    async a_context()
): ...

with (
    # sync_context() as foo,
    async a_context()
): ...

with (async a_context()): ...

with async a_context(): ...

Acknowledgements

Thanks to Rob Rolls for proposing with async. Thanks also to the many other people with whom we discussed this problem and possible solutions at the PyCon 2025 sprints, on Discourse, and at work.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.