Python contextmanager decorator vs class context manager
Compare Python's @contextmanager decorator with class-based context managers: exception handling, state, reusability, and guidance for choosing the right approach.

When you need to manage resources in Python, the with statement is the standard tool. Underneath it sits the context manager protocol, which you can implement in two distinct ways: by writing a class with __enter__ and __exit__ methods, or by using the @contextmanager decorator from contextlib to turn a generator function into a context manager. The choice between the @contextmanager decorator and a class-based context manager affects how you handle exceptions, store state, and structure your code. This article explains the practical differences and gives you concrete criteria for picking one over the other.
The Two Ways to Write a Context Manager in Python
The with statement requires an object that implements the context manager protocol. That protocol consists of two methods: __enter__ is called when execution enters the block, and __exit__ is called when the block finishes, whether normally or via an exception. The __exit__ method receives the exception type, value, and traceback if an exception occurred, and it can suppress the exception by returning a truthy value.
The class-based approach implements these methods directly. The decorator-based approach uses a generator function with a yield statement. When you decorate such a function with @contextmanager, the code before yield runs as part of __enter__, the value yielded becomes the result of the with expression, and the generator is resumed as part of __exit__ so code after the yield can run during cleanup. Both approaches satisfy the same protocol, but they differ in how you express the logic.
How the Decorator Version Works
Here is a minimal @contextmanager implementation:
from contextlib import contextmanager
@contextmanager
def managed_file(path, mode):
f = open(path, mode)
try:
yield f
finally:
f.close()When you use with managed_file("data.txt", "r") as f:, the generator runs until the yield statement, which produces the file object. The with block executes, and when it finishes, the generator resumes after the yield. The finally block ensures the file is closed even if an exception occurs inside the with block.
The decorator handles the plumbing. It wraps your generator so that the __enter__ method calls next() on it, and the __exit__ method either calls next() again (if no exception) or throw() (if an exception occurred). The generator's finally block runs in both cases, which makes cleanup straightforward.
One key limitation: a decorated generator is designed to yield exactly once for a single with block. The wrapper expects the generator to stop when it is resumed during cleanup. If the generator yields again instead of finishing, the wrapper raises a RuntimeError. Also, the context manager object produced by a call to the decorated function contains a one-shot generator, so that same object cannot be entered a second time. This makes the decorator approach a poor fit when you need a reusable context manager object or one that keeps state across multiple with blocks.
How the Class-Based Version Works
The class-based approach gives you full control over the protocol methods:
class ManagedFile:
def __init__(self, path, mode):
self.path = path
self.mode = mode
self.file = None
def __enter__(self):
self.file = open(self.path, self.mode)
return self.file
def __exit__(self, exc_type, exc_val, exc_tb):
if self.file:
self.file.close()
# Return False to propagate exceptions, or True to suppress them
return FalseHere __enter__ does the setup and returns the resource object. __exit__ performs cleanup. The method signature gives you access to the exception details, and you can decide whether to suppress the exception by returning True or False. This is more explicit than the generator version, where exception suppression is handled differently.
Because the class is a regular object, you can store state on self and use it across multiple with blocks. You can also implement additional methods that the context manager exposes, making it a richer object than a simple generator wrapper.
Key Behavioral Differences
Exception Handling
The most significant difference lies in how each approach handles exceptions. In the class-based version, __exit__ receives the exception details and can decide to suppress it. If it returns True, the exception is swallowed and execution continues after the with block. If it returns False or None, the exception propagates.
In the decorator version, exceptions are handled by the generator's internal logic. If an exception occurs inside the with block, the decorator throws that exception into the generator at the yield point. This means the generator can catch it, but only within the try/except structure you write. To suppress an exception, you need to catch it inside the generator and avoid re-raising it. For example:
@contextmanager
def suppress_errors():
try:
yield
except ValueError:
passIf you want the exception to propagate, you simply don't catch it. This is often more concise than the class-based approach, but it can be less obvious when the exception is intentionally swallowed.
State and Reusability
The class-based context manager is a persistent object. You can instantiate it once and use it multiple times, as long as __enter__ resets the state appropriately. This is useful for context managers that need to maintain configuration or accumulate data across invocations.
The decorator version is tied to a single generator execution. A call to the decorated function creates one generator, and that generator is consumed by the with block. To use the context manager again, you call the function again, which creates a fresh generator. The decorator approach therefore does not keep state on a context manager object across separate with blocks unless you store that state in external variables. If you need to accumulate state, the class approach is more natural.
Return Value from __enter__
In the class version, __enter__ can return any object, including self if you want to expose methods on the context manager itself. In the decorator version, the value yielded is the return value of __enter__. You can yield any object, but you cannot easily return self because the generator is not the context manager object; the decorator wraps it. To expose methods, you would need to yield a separate object that carries those methods.
When to Use the Decorator Approach
The @contextmanager decorator shines for simple resource management where the setup and teardown are linear and you don't need complex state. Typical use cases include:
- Opening and closing files, network connections, or database transactions.
- Temporarily changing configuration or environment variables.
- Acquiring and releasing locks.
- Timing code blocks.
The decorator reduces boilerplate. You write a single function with a yield instead of a class with three methods. This is especially readable when the logic is short and the cleanup is deterministic. For example, a temporary directory context manager:
@contextmanager
def temp_dir():
import tempfile, shutil
path = tempfile.mkdtemp()
try:
yield path
finally:
shutil.rmtree(path)This is concise and clear. The class version would require more lines to achieve the same effect.
When to Use the Class Approach
The class-based approach is the better choice when you need any of the following:
- Persistent state across multiple
withblocks: For example, a connection pool that tracks usage counts. - Custom
__enter__logic that depends on the instance state: You can pre-configure the object before entering the block. - Exposing methods on the context manager itself: If you want
with manager as m:and then callm.some_method(), the class approach lets you returnselffrom__enter__. - Fine-grained exception handling: When you need to inspect the exception type, value, and traceback separately and decide based on them, the explicit
__exit__signature is clearer. - Reusability: If you need to enter the same context manager multiple times, a class instance can be designed for reuse, whereas a single decorated generator cannot.
Consider a context manager that measures time and accumulates statistics:
class Timing:
def __init__(self):
self.total_time = 0
def __enter__(self):
import time
self.start = time.perf_counter()
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.total_time += time.perf_counter() - self.start
return FalseYou can reuse the same Timing object across multiple with blocks, accumulating the total time. The decorator approach would require an external variable to hold the accumulated time, which is less encapsulated.
Performance and Overhead Considerations
Both approaches have negligible overhead for most applications, but there is a conceptual difference. The decorator version wraps your generator in a _GeneratorContextManager object, which adds a layer of indirection. The class version is a direct implementation of the protocol, so method calls go straight to your __enter__ and __exit__. In practice, the difference is micro-level and unlikely to matter unless you create and enter context managers in a tight loop with millions of iterations.
The generator version also has the overhead of yield and next() calls, but again, this is minimal. If you are writing performance-critical code, you should profile rather than assume one is faster. The real performance consideration is often the resource management itself, not the context manager wrapper.
Compatibility and Maintainability
The @contextmanager decorator is part of contextlib and has been available since Python 2.5, so it is widely compatible. The class-based approach does not require an extra import; you only implement the protocol methods. Both work in current Python versions.
From a maintainability perspective, the class approach is more explicit. The __enter__ and __exit__ methods clearly separate setup and teardown, and the exception handling is visible in the method signature. The decorator approach hides the control flow inside a generator, which can be less obvious to developers unfamiliar with the pattern. However, the decorator version is often shorter and easier to read for simple cases.
Testing also differs. A class-based context manager can be unit-tested by calling __enter__ and __exit__ directly, which gives you fine-grained control. The decorator version is usually tested through the with statement, although its context manager object also exposes the same __enter__ and __exit__ methods. In practice, both are testable, but the class approach makes internal state directly accessible on self.
Making the Choice: A Decision Guide
Use the @contextmanager decorator when:
- The setup and teardown are linear and fit in a single function.
- You don't need to maintain state between different
withblocks. - You don't need to expose methods on the context manager object.
- You want the shortest possible code.
Use the class-based approach when:
- You need to store state on the context manager instance.
- You want to reuse the same context manager object multiple times.
- You need to implement custom exception suppression logic that depends on the exception details.
- You want to return
selffrom__enter__to expose methods. - The context manager is complex enough that separating
__enter__and__exit__improves readability.
There is no universal winner. The decision depends on the specific requirements of your resource management code. If you are unsure, start with the decorator for simple cases and switch to a class when you find yourself fighting the generator's limitations.
A final note on error handling: in the class version, returning True from __exit__ suppresses the exception. In the decorator version, you suppress by catching the exception inside the generator. If you need to suppress selectively based on the exception type, the class version's explicit exc_type parameter is more readable. If you simply want to ensure cleanup, the decorator's finally block is sufficient and often cleaner.
Both approaches are valid Python idioms. Understanding the behavioral differences allows you to choose the one that fits your code's structure and your team's readability preferences.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.