Skip to content

Python Context Managers: with Statement and contextlib

  • How the with statement calls __enter__ and __exit__ to guarantee cleanup.
  • How to write a context manager as a class and as a generator with contextlib.contextmanager.
  • How suppress, nullcontext, and ExitStack handle optional and dynamic resources.
  • How async context managers work with async with and asynccontextmanager.
  • Practical patterns for temporary files, locks, and transactions.

A context manager pairs setup and teardown so the teardown always runs, even when the block raises. The with statement calls __enter__ on entry and __exit__ on exit, and the standard library’s contextlib module turns a generator into a context manager with a decorator. The guarantee that cleanup runs on every path, including exceptions and early returns, is what makes context managers the right tool for files, locks, transactions, and any resource that must be released. The feature has been in Python since 2.5, with async context managers added in 3.5.

Resources that must be closed or released are easy to leak. Open a file, and if an exception fires before the close, the file handle stays open until garbage collection happens to run. The pattern “open, use, close” works in the happy path and fails everywhere else.

Manual cleanup:

f = open("orders.txt", "w")
f.write("order 1023")
# if write raises, f never closes
f.close()

A with block turns the cleanup into a guarantee: __exit__ runs no matter how the block ends.

A context manager implements __enter__ and __exit__. __enter__ runs first and its return value is bound to the as variable. __exit__ runs on exit, receiving the exception type, value, and traceback if the block raised; returning True suppresses the exception, which is rare.

class LogOperation:
def __init__(self, name):
self.name = name
def __enter__(self):
print(f"start {self.name}")
return self
def __exit__(self, exc_type, exc_val, exc_tb):
if exc_type is None:
print(f"end {self.name}")
else:
print(f"end {self.name} with {exc_type.__name__}")
return False # do not suppress
with LogOperation("fetch orders") as op:
print("working")
# start fetch orders
# working
# end fetch orders

Returning False (or nothing) lets any exception propagate. Returning True swallows it, which you should do only with deliberate intent, since it hides errors.

For most cases, contextlib.contextmanager is shorter. A generator yields exactly once: the code before yield is the setup, the yielded value is what as receives, and the code after yield is the teardown. An exception in the with block is thrown into the generator at the yield.

from contextlib import contextmanager
@contextmanager
def log_operation(name):
print(f"start {name}")
try:
yield name
finally:
print(f"end {name}")
with log_operation("fetch orders"):
print("working")
# start fetch orders
# working
# end fetch orders

The try/finally ensures the teardown runs even when the block raises, mirroring what __exit__ does in the class form. This is the form you will reach for most often.

contextlib.suppress(*exceptions) ignores the listed exceptions, replacing a try/except/pass that swallows too broadly. nullcontext(value) is a no-op context manager that yields its argument, useful as a placeholder when a context manager is optional. ExitStack manages a dynamic number of context managers, closing them in reverse order.

from contextlib import suppress, nullcontext, ExitStack
# ignore a missing file instead of crashing
with suppress(FileNotFoundError):
data = open("missing_config.txt").read()
print("read", len(data), "bytes")
print("continued past the missing file")
# an optional lock: use the real lock, or a no-op when there is nothing to protect
def critical_section(lock=None):
cm = lock if lock else nullcontext()
with cm:
print("in the critical section")
critical_section()
# a dynamic number of files, cleaned up in reverse
files = ["a.txt", "b.txt", "c.txt"]
with ExitStack() as stack:
handles = [stack.enter_context(open(f, "w")) for f in files]
for h in handles:
h.write("order")
print(f"opened {len(handles)} files")
# opened 3 files

ExitStack is the answer when you do not know until runtime how many resources you will open; it guarantees every one is closed even if a later open fails.

For asyncio code, async with calls __aenter__ and __aexit__, both coroutines. contextlib.asynccontextmanager turns an async generator into one. Use them for resources held across awaits, such as an async HTTP client session.

import asyncio
from contextlib import asynccontextmanager
@asynccontextmanager
async def timed_operation(name):
print(f"start {name}")
try:
yield name
finally:
print(f"end {name}")
async def main():
async with timed_operation("fetch"):
await asyncio.sleep(0.01)
print("working")
asyncio.run(main())
# start fetch
# working
# end fetch

The shape mirrors the synchronous decorator; only the keywords change.

OrdersPortal writes a batch of orders to a temporary directory and must remove it even if a write fails. contextlib.ExitStack and tempfile.TemporaryDirectory together guarantee the cleanup.

import tempfile
from contextlib import ExitStack
def write_batch(orders):
with ExitStack() as stack:
work_dir = stack.enter_context(tempfile.TemporaryDirectory())
print(f"created {work_dir}")
for order in orders:
path = f"{work_dir}/order_{order}.txt"
with open(path, "w") as f:
f.write(f"order {order}")
# simulate a failure to prove cleanup still runs
if any(orders):
raise RuntimeError("batch aborted")
return work_dir
try:
write_batch([1023, 1024])
except RuntimeError as e:
print(f"caught: {e}")
# created <temp dir>
# caught: batch aborted <- the temp dir is gone despite the raise

ExitStack closes the temporary directory in its __exit__, which runs even though the body raised. Writing the files inside the same stack means a failure partway through still cleans up everything opened before it.

  • Always use with for open. The file is closed on every path, including exceptions and early returns. There is rarely a reason to call close directly.
  • Prefer the generator form for one-off managers. contextmanager is shorter and clearer than a class when you do not need state across calls.
  • Push callbacks onto an ExitStack. stack.callback(cleanup_func) registers a teardown function; stack.push(closer) registers an object with a close method. Both run in reverse order at exit.
  • Suppress narrowly. suppress(FileNotFoundError) swallows only that exception. A bare except: pass hides programming errors and should never be used for cleanup.
  • Forgetting try/finally around yield. Without it, an exception in the with block aborts the generator before the teardown runs, defeating the purpose. Always wrap the yield in try/finally.
  • Yielding more than once. A contextmanager generator must yield exactly once. A second yield raises RuntimeError, since __enter__ has no way to call the generator twice.
  • Suppressing exceptions by accident. Returning True from __exit__ swallows the exception. Return False unless you specifically mean to ignore the error.
  • Using a non-context-manager in with. with some_dict: raises AttributeError because the object has no __enter__. Wrap the object or reach for nullcontext when a context is optional.
  • Leaking across awaits without async with. In async code, a plain with over a resource you then await blocks the loop. Use async with so the resource is released asynchronously.
Situation Use
A resource that must close or release with and a context manager
A cleanup tied to a specific scope contextmanager generator
An optional or no-op context nullcontext
A dynamic number of resources ExitStack
A sync resource held across awaits async with and asynccontextmanager

Reach for a context manager whenever cleanup must be guaranteed. For one-time setup that does not need teardown, a plain function call is simpler.

The with statement and the class protocol date to Python 2.5. contextlib.contextmanager, suppress, nullcontext, and ExitStack are all available in Python 3.9 and later. Async context managers and asynccontextmanager arrived in Python 3.5 with async/await. The examples here run on Python 3.9 and later.

1. What does __exit__ return, and why does it matter? It returns a truthy value to suppress the exception that occurred in the block, or a falsy value to let it propagate. Most managers return False (or nothing) so errors are not hidden; suppress is the rare case that returns True deliberately.

2. Why must yield in a contextmanager be wrapped in try/finally? An exception in the with block is thrown into the generator at the yield. Without try/finally, the generator unwinds and the teardown after yield never runs, so the resource leaks exactly when cleanup matters most.

3. What does ExitStack add over multiple with statements? It handles a number of contexts not known until runtime, and it closes them in reverse order even if opening a later one fails. Fixed with a, b, c: cannot express that, because the number of items is fixed at write time.

4. Senior scenario: a service leaks file descriptors over time, and the code uses contextmanager. What is the likely cause? The generator’s teardown is not wrapped in try/finally, so an exception in the with body throws at the yield and unwinds past the cleanup. The file is never closed because the close() call after the bare yield never executes. Wrap the yield in try/finally so the cleanup runs on the exception path.

  • with guarantees __exit__ runs on every exit path, including exceptions.
  • contextlib.contextmanager turns a generator into a manager; wrap yield in try/finally.
  • suppress ignores specific exceptions; nullcontext is a no-op placeholder; ExitStack handles dynamic resources.
  • Use async with and asynccontextmanager for resources held across awaits.