Why does contextlib.ExitStack.enter_context reject an async context manager, and what replaces it?

### The refusal, precisely `contextlib.ExitStack` is a purely synchronous machine. `enter_context(cm)` looks up `__enter__` and `__exit__` on the *type* of the object, calls `__enter__` immediately, and pushes a callback that will call `__exit__` during unwinding. An object produced by `@contextlib.asynccontextmanager`, or any class implementing `__aenter__`/`__aexit__`, has neither method, so the lookup fails and `enter_context` raises `TypeError` — *object does not support the context manager protocol*. Nothing is entered, nothing is registered, and the resource is left unopened. That is the good outcome: the alternative would be a half-opened resource with no scheduled cleanup. A detail worth noticing: the `with` **statement** produces a friendlier version of the same error, adding that the object supports the asynchronous protocol and asking whether you meant `async with`. `ExitStack.enter_context` gives the bare message with no such hint, so recognising the plain wording matters when the failure comes from a stack rather than a `with`. ### The replacement `contextlib.AsyncExitStack` is the async-capable counterpart, and it is itself an asynchronous context manager, so it is used as `async with AsyncExitStack() as stack`. Its additions are: - `await stack.enter_async_context(cm)` — awaits `cm.__aenter__()`, returns its value, and schedules `cm.__aexit__` for unwinding. - `stack.push_async_callback(func, *args, **kwargs)` — registers a coroutine function to be awaited during unwinding. Like the synchronous `callback`, it is for cleanup that is a plain call rather than a context manager, and the return value it registers is ignored, so it can never suppress an exception. - `stack.push_async_exit(exit)` — registers an object's `__aexit__` (or a coroutine function with that signature) without entering anything, which is what you want when a resource was opened elsewhere and only its release needs to be owned by the stack. - `await stack.aclose()` — unwinds everything immediately, the async analogue of closing the stack early. All of these are *awaited* at unwind time, which is precisely what a synchronous stack cannot do. ### One stack, both flavours `AsyncExitStack` inherits the synchronous half of the API — `enter_context`, `callback`, `push` and `pop_all` all exist on it. That is the practical point most candidates miss: you do **not** need two stacks when a routine mixes an opened file with an awaited session. Register each resource with the method matching its own protocol and the single stack unwinds them all in strict reverse order, awaiting the async ones and calling the sync ones. Keeping one stack preserves the true release order across the mixture; two parallel stacks cannot. ### Why a stack at all The stack earns its place when the number of resources is not known when the code is written: a variable-length list of endpoints, an optional resource entered only under a flag, or a set built from configuration. Nesting `async with` blocks demands a fixed, statically-written shape; a stack lets a loop enter as many as it finds while still guaranteeing that everything entered is released, including when entry number four raises after three succeeded. ```python async with AsyncExitStack() as stack: sessions = [await stack.enter_async_context(open_probe(name)) for name in probe_names] ``` If `open_probe` fails on the fifth name, the four already entered are unwound before the exception leaves the block. ### Transferring ownership `pop_all()` is inherited and works the same way as on the synchronous stack: it moves every registered callback to a fresh stack and clears the original, so exiting the original block releases nothing. The idiom is to build resources under the safety of a stack, and — only once every step has succeeded — transfer them to a long-lived object that will unwind them later with `await stack.aclose()`. It converts an all-or-nothing setup routine into a factory that hands back a live, owned resource bundle. ### Unwinding a mixed stack Unwinding runs the registered exits in strict reverse order of registration, awaiting each asynchronous one in turn. It is sequential, not concurrent: an `AsyncExitStack` is a cleanup ledger, not a way to release several resources at once, so a teardown that awaits something slow costs that time at every exit. If one exit itself raises, the remaining exits still run and the errors chain, so the first failure is not lost — but a cleanup routine that can fail is still worth wrapping so it cannot mask the exception that caused the unwinding in the first place. ### Common failure modes Forgetting `await` in front of `enter_async_context` binds a coroutine object rather than the resource, and the block then operates on something that is not the session at all. Passing a *coroutine object* to `push_async_callback` instead of the function plus its arguments creates a never-awaited coroutine and a warning at teardown. And entering the stack itself with plain `with` fails immediately, since `AsyncExitStack` implements only the asynchronous protocol.