contextlib
Published by Brayan K
The contextlib module gives you tools for working with the with-statement — most notably @contextmanager, which turns a simple generator into a reusable setup-and-cleanup context manager.
Part of the free Python course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.
A yield divides acquisition from the managed body
A generator-based context manager acquires something before yield and releases it when the with block finishes. The yielded object becomes the value after as. The decorator supplies the context-manager protocol; it does not make an ordinary generator safe by itself. Context Managers & the with Statement in Depth owns the underlying enter and exit methods.
from contextlib import contextmanager
@contextmanager
def labelled(name):
print("enter", name)
try:
yield name.upper()
finally:
print("leave", name)
with labelled("draft") as label:
print("body", label)
# ✅ Expected output:
# enter draft
# body DRAFT
# leave draftCalling labelled("draft") creates a manager; entering with runs it to yield. Leaving with resumes it. Put cleanup in finally around yield so it runs when the body returns normally or raises. Code merely placed after yield is skipped if the exception propagates through that point.
from contextlib import contextmanager
@contextmanager
def tracked():
print("acquired")
try:
yield "resource"
finally:
print("released")
try:
with tracked():
raise ValueError("bad record")
except ValueError as error:
print("caller:", error)
# ✅ Expected output:
# acquired
# released
# caller: bad recordAcquisition itself can fail before yield. Release only resources that were actually acquired. Once ownership has been established, arrange cleanup immediately; a later failure must not strand an earlier resource. ExitStack below makes that rule manageable for a variable number of resources.
The generator must yield exactly once
from contextlib import contextmanager
@contextmanager
def missing_resource():
if False:
yield "unused"
with missing_resource():
print("body")
# ✅ Expected error:
# RuntimeError: generator didn't yieldfrom contextlib import contextmanager
@contextmanager
def twice():
yield "first"
yield "second"
with twice() as value:
print(value)
# ✅ Expected output:
# first
# ✅ Expected error:
# RuntimeError: generator didn't stopA context manager is not a loop over resources. A second yield violates its exit protocol. If a caller needs multiple values, yield one collection or write a separate iterator. Also create a fresh generator manager for each use: call the decorated factory inside each with statement. Saving one manager and re-entering it tries to reuse a one-shot generator, not rerun the factory.
The decorated factory can be called many times, while each returned manager has one lifetime. The factory is reusable; its individual generator-manager instances are not.
Swallowing an exception changes what the caller knows
from contextlib import contextmanager
@contextmanager
def careless_log():
try:
yield
except ValueError as error:
print("logged:", error)
with careless_log():
raise ValueError("invalid quantity")
print("caller continued")
# ✅ Expected output:
# logged: invalid quantity
# caller continuedThe body exception is thrown back into the generator at yield. Here the except block handles it and the generator finishes normally, so the caller continues. Logging alone is not neutral: add a bare raise after logging when the operation must remain failed. Suppression should be a deliberate part of the manager contract.
from contextlib import suppress
settings = {"theme": "dark"}
with suppress(KeyError):
del settings["obsolete"]
print(settings)
try:
with suppress(KeyError):
int("many")
except ValueError:
print("unrelated error remains visible")
# ✅ Expected output:
# {'theme': 'dark'}
# unrelated error remains visibleRemoving an optional dictionary key is a small operation for which absence is acceptable. Keep the with body this narrow. suppress(Exception) around a processing pipeline can hide a broken conversion, missing dependency or genuine bug. Exception hierarchy and chaining are owned by Custom Exceptions & Exception Chaining; these examples use ordinary exceptions across Python 3.11–3.14.
ExitStack unwinds resources in reverse acquisition order
from contextlib import ExitStack, contextmanager
@contextmanager
def open_label(name):
print("open", name)
try:
yield name
finally:
print("close", name)
try:
with ExitStack() as stack:
labels = [stack.enter_context(open_label(name))
for name in ["source", "destination"]]
print("ready", labels)
raise ValueError("validation failed")
except ValueError as error:
print("caller:", error)
# ✅ Expected output:
# open source
# open destination
# ready ['source', 'destination']
# close destination
# close source
# caller: validation failedenter_context enters a manager and registers its exit only after entry succeeds. Exits run in reverse order, like nested with statements. The destination closes before the source. This is useful when configuration decides how many resources to acquire. If a later entry fails, earlier successful entries are still registered for cleanup.
from contextlib import ExitStack
events = []
with ExitStack() as pending:
pending.callback(events.append, "release first")
pending.callback(events.append, "release second")
owned = pending.pop_all()
events.append("transferred")
print(events)
owned.close()
print(events)
# ✅ Expected output:
# ['transferred']
# ['transferred', 'release second', 'release first']callback registers a plain callable with its arguments; it does not receive exception details and cannot suppress an exception. push registers an exit-style callable. Use enter_context for a context manager instead of manually calling enter and then attempting to register cleanup.
pop_all transfers callbacks into a new stack without running them. The old stack becomes empty. The recipient must close the new stack or use it in a with statement; transferring ownership is not cancelling cleanup. ExitStack does not run its callbacks merely because the object is garbage-collected. Keep that lifetime explicit.
Adapt an existing lifetime without taking ownership accidentally
from contextlib import closing, nullcontext
from io import StringIO
with closing(StringIO("owned")) as owned:
print(owned.read())
print(owned.closed)
borrowed = StringIO("borrowed")
with nullcontext(borrowed) as stream:
print(stream.read())
print(borrowed.closed)
borrowed.close()
# ✅ Expected output:
# owned
# True
# borrowed
# Falseclosing calls close on exit, which helps with an object that has close but lacks its own context-manager support. Prefer the native manager when one exists. nullcontext supplies the object and performs no cleanup; it is useful when the caller retains ownership of a borrowed resource.
Closing a stream supplied by someone else can break their later work. Document whether a function borrows or consumes the resource. The example closes the borrowed stream explicitly only after the borrowing block has finished.
Complete cleanup without hiding the original failure
Fill the two gaps so the manager yields the resource and always records its release. The caller should still catch the original ValueError. Each hint supplies one literal replacement.
from contextlib import contextmanager
events = []
@contextmanager
def ticket():
try:
___ "ticket"
___:
events.append("released")
try:
with ticket() as value:
events.append(value)
raise ValueError("cancelled")
except ValueError:
events.append("caller caught failure")
print(events)
# 👉 replace ___ with yield
# 👉 replace ___ with finally
# ✅ Expected output:
# ['ticket', 'released', 'caller caught failure']Build a transaction-like registration scope
Given an initially empty active list, write a managed registration that appends a name on entry, yields that same name and removes it on exit. Use ExitStack to register alpha and beta, record the active names inside the block, then deliberately raise ValueError. Catch it outside and print the records and final active list. This is a lifetime exercise, not a database transaction: list mutation provides no rollback for external work.
from contextlib import ExitStack, contextmanager
active = []
records = []
@contextmanager
def registered(name):
active.append(name)
try:
yield name
finally:
active.remove(name)
records.append("removed " + name)
try:
with ExitStack() as stack:
for name in ["alpha", "beta"]:
stack.enter_context(registered(name))
records.append(",".join(active))
raise ValueError("abort")
except ValueError:
records.append("caught")
print(records)
print(active)
# ✅ Expected output:
# ['alpha,beta', 'removed beta', 'removed alpha', 'caught']
# []
Practice quiz
What does this program print? from contextlib import nullcontext with nullcontext("A") as value: print(value)
- A
- None
- True
- A None
Answer: A. nullcontext yields its supplied object and performs no cleanup.
A generator manager logs a ValueError thrown by the with body, then ends without raise. What happens?
- The original error always reaches the caller
- The manager suppresses that error
- Python retries the body
- The generator yields again
Answer: The manager suppresses that error. Finishing normally after catching the injected exception tells the wrapper that it was handled.
What does this program print? from contextlib import ExitStack items = [] with ExitStack() as stack: stack.callback(items.append, "A") stack.callback(items.append, "B") print(items)
- ['A', 'B']
- []
- ['B', 'A']
- ['A']
Answer: ['B', 'A']. Callbacks unwind in reverse registration order.
Which construct guarantees post-acquisition cleanup when the with body raises?
- An ordinary statement after yield
- A second yield
- A return before yield
- A finally block surrounding yield
Answer: A finally block surrounding yield. The injected body exception passes through finally whether or not it is caught.
What does this program print? from contextlib import suppress with suppress(KeyError): {}["missing"] print("continued")
- continued
- KeyError
- None
- False
Answer: continued. Only the selected KeyError is suppressed.
After transferred = stack.pop_all(), who owns the pending cleanup?
- Nobody; the callbacks ran immediately
- transferred, which must later be closed
- The old stack still owns it
- The garbage collector is guaranteed to run it
Answer: transferred, which must later be closed. pop_all transfers callbacks without invoking them.
Which object should be created anew for each with use?
- The contextlib module
- The decorated factory function
- The generator-manager instance returned by the factory
- Every exception class
Answer: The generator-manager instance returned by the factory. The factory is reusable, but each generator-manager instance is one-shot.
What does ExitStack.callback receive automatically when the body raises?
- The exception type
- The exception value
- The traceback
- None of those; only its registered arguments
Answer: None of those; only its registered arguments. callback adapts an ordinary callable; exit-style handling belongs to push or enter_context.
Continue this course
- Previous: Thread-Safe Queues (queue)
- Next: Temporary Files & Directories — Create auto-cleaning temp files and folders with the tempfile module
- Quick reference: Python cheat sheet