Skip to content
Tutorials Center
My learning

Topics

Lesson 70 of 149 ยท Files and Errors

Context Managers

Understand how Python's with statement works, write context managers with __enter__ and __exit__ or contextlib.contextmanager, and use suppress and ExitStack.

You've already used the with statement to open files, and you know it closes the file for you even when something goes wrong. That isn't special file magic. with works with any object that follows a small protocol, and such an object is called a context manager.

Context managers capture a pattern that shows up everywhere: set something up, do some work, then tear it down, no matter what. Open and close a file. Acquire and release a lock. Start and stop a timer. Change a setting and change it back. In this lesson you'll see exactly what with does, write your own context managers in two different ways, and meet the helpers in the contextlib module.

What with does

Here's the familiar version and, below it, roughly what Python does for you behind the scenes:

Python
with open("notes.txt", "w", encoding="utf-8") as file:
    file.write("hello")
Python
manager = open("notes.txt", "w", encoding="utf-8")
file = manager.__enter__()
try:
    file.write("hello")
finally:
    manager.__exit__(...)   # closes the file

So a context manager is any object with two special methods:

  • __enter__() runs when the with block starts. Whatever it returns is bound to the name after as.
  • __exit__() runs when the block ends, whether it finished normally, hit return or break, or raised an exception.

The try/finally you learned in Exceptions and try/except is still doing the work; with just packages it so you can't forget it.

Writing a context manager class

To make your own, write a class with __enter__ and __exit__ methods. Classes get a full lesson in Classes and Objects; here, focus on when each method runs:

Python A class-based context manager

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

__exit__ receives three arguments describing any exception that ended the block: its type, the exception object and its traceback. When the block finishes normally, all three are None.

The return value of __exit__ matters:

  • Return False (or nothing, which is None) and the exception keeps propagating after clean-up. This is almost always what you want.
  • Return True and the exception is suppressed: execution continues after the with block as if nothing went wrong. Use this very deliberately.

A practical example: a timer

Measuring how long a piece of code takes is a classic use. __enter__ records the start time, and __exit__ computes the elapsed time:

Python A timing context manager

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Because __enter__ returns self, the as timer name gives you the object afterward, so you can still read timer.elapsed once the block is done. time.perf_counter() is the right clock for measuring durations: it's high-resolution and never jumps backward.

The easy way: @contextmanager

Writing a class works, but for many context managers it's more ceremony than you need. The contextlib module offers a decorator that turns a generator function into a context manager. Everything before yield is the setup, the yielded value is what as receives, and everything after yield is the teardown:

Python contextlib.contextmanager

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The try/finally around yield is important. If the with block raises an exception, it is re-raised at the yield inside your generator. Without finally, the code after yield would be skipped and the closing tag would never print. The Generators and Decorators lessons explain the two features this builds on.

Here's a more realistic one: a context manager that creates a file, hands it to the block, and reports how big it ended up:

Python A file-writing helper

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Ready-made helpers in contextlib

The standard library already includes several context managers you'd otherwise have to write yourself.

suppress ignores specific exceptions. It's a compact replacement for try / except SomeError: pass:

Python
from contextlib import suppress
from pathlib import Path

with suppress(FileNotFoundError):
    Path("old-cache.txt").unlink()

redirect_stdout temporarily sends everything print() writes to another file-like object, which is handy for capturing output:

Python suppress and redirect_stdout

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that suppress ends the whole block at the first matching exception, just like try would. The second print inside it never runs.

ExitStack is for when you don't know in advance how many context managers you need, for example opening a list of files whose length depends on user input. You call stack.enter_context(...) for each one, and they're all closed, in reverse order, when the with ExitStack() as stack: block ends.

Tip: you can combine several context managers in one statement. Since Python 3.10 you may wrap them in parentheses and split them across lines:

Python
with (
    open("input.txt", encoding="utf-8") as source,
    open("output.txt", "w", encoding="utf-8") as target,
):
    target.write(source.read().upper())

Where you'll meet context managers

Once you recognize the pattern, you'll see it all over Python:

  • open() and Path.open() for files.
  • threading.Lock() for locks: the lock is released even if the code inside fails.
  • sqlite3 connections, which commit a transaction on success and roll it back on error.
  • decimal.localcontext() to change decimal precision temporarily.
  • unittest.mock.patch() in tests, which swaps something out and then restores it.

Whenever you write code that must "undo" something afterward, consider wrapping it in a context manager.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In with manager as value:, what is bound to value?

    The as name receives the return value of enter. Many managers return self, and open() returns the file object.
  2. 2. An exception is raised inside a with block. When does exit run?

    exit runs on every exit from the block. It receives the exception details and decides whether to let it propagate.
  3. 3. What happens if exit returns True after an exception?

    A true return value tells Python the exception was handled, so it's swallowed. Return False or None to let it propagate.
  4. 4. In a @contextmanager generator, why wrap yield in try/finally?

    An exception in the block is re-raised at the yield. Without finally, the code after yield would be skipped.
  5. 5. Which helper replaces try/except FileNotFoundError/pass in one line?

    with suppress(FileNotFoundError): silently ends the block if that exception occurs.

Summary

  • A context manager is an object with __enter__ and __exit__; the with statement calls them around a block, like a built-in try/finally.
  • __enter__'s return value is bound by as; __exit__ always runs and receives any exception's type, value and traceback.
  • __exit__ returning a true value suppresses the exception; normally return False or None.
  • @contextlib.contextmanager turns a generator into a context manager: setup, yield, teardown (inside finally).
  • contextlib also provides suppress, redirect_stdout and ExitStack.

Next: Debugging and assert, where you'll learn to read tracebacks and track down bugs with print, assert and logging.