Skip to content

Python with ... as: Reliable Cleanup (PEP 343)

  • What the with statement guarantees, and the exact try/finally code it replaces.
  • What the as target receives: the return value of __enter__, not the context manager.
  • How multiple managers, parenthesized groups (Python 3.10) and tuple targets work.
  • How exceptions flow through __exit__, and when cleanup does not run.
  • The traps: closed files after the block, tuples that are not managers, and sqlite3 connections that stay open.

with EXPRESSION as TARGET: evaluates the expression to get a context manager, calls its __enter__() method, binds the return value to TARGET, runs the block and then always calls __exit__(), whether the block finished normally, returned, broke out of a loop or raised. The statement came from PEP 343 in Python 2.5 (enabled with a __future__ import there and always on from 2.6). Python 3.1 added several managers in one statement and Python 3.10 made parenthesized, multi-line groups official. It is the standard way to manage files, locks, database transactions and any other set-up and tear-down pair in Python 3.14.

This page focuses on the statement and its as clause. For writing your own managers with contextlib, see Context managers.

Resources must be released even when code fails. Without with, every use needs a try/finally, and every forgotten finally is a leaked file handle, an unreleased lock or an uncommitted transaction. The cleanup also ends up far from the set-up that it belongs to.

The samples on this page are plain scripts: save each as a .py file and run it with python3 file.py. They were run on CPython 3.14.6 and the output shown is from that run; the parenthesized form in the realistic example needs Python 3.10 or later.

import os
import tempfile
path = os.path.join(tempfile.mkdtemp(), "orders-export.csv")
# Before: try/finally, and the cleanup line must never be forgotten.
f = open(path, "w", encoding="utf-8")
try:
f.write("order_id,total\nORD-1001,59.90\n")
finally:
f.close()
# After: the with statement calls the cleanup for you; `as` names the file.
with open(path, encoding="utf-8") as export:
print(export.read().splitlines())
print("closed after the block:", export.closed)

Output:

['order_id,total', 'ORD-1001,59.90']
closed after the block: True

The language reference defines with EXPRESSION as TARGET: SUITE as equivalent to this fragment (simplified; sys must be imported):

manager = (EXPRESSION)
enter = manager.__enter__
exit = manager.__exit__
value = enter()
hit_except = False
try:
TARGET = value
SUITE
except:
hit_except = True
if not exit(*sys.exc_info()):
raise
finally:
if not hit_except:
exit(None, None, None)

Four consequences follow directly from that expansion:

  1. TARGET receives enter()’s return value. Many managers return self, but not all do.
  2. __exit__ runs only if __enter__ succeeded. If __enter__ raises, there is nothing to clean up and the exception propagates.
  3. __exit__ decides whether an exception propagates. A true return value suppresses it; a false one (including None) re-raises it.
  4. The as name is an ordinary assignment. It stays bound after the block. This differs from except E as name, where the name is deleted at the end of the clause.
import contextlib
import threading
class AuditedSession:
"""A manager whose __enter__ returns something other than itself."""
def __enter__(self):
print("enter: open audit session")
return {"user": "agent-7", "actions": []} # this is what `as` binds
def __exit__(self, exc_type, exc, tb):
print(f"exit: exc_type={exc_type.__name__ if exc_type else None}")
return False # do not suppress
with AuditedSession() as session:
session["actions"].append("viewed ORD-1001")
print(session) # the name outlives the block
# What `as` binds depends on __enter__, not on the expression:
with open(__file__, encoding="utf-8") as f:
print("open ->", type(f).__name__)
lock = threading.Lock()
with lock as acquired:
print("Lock ->", acquired)
with contextlib.suppress(KeyError) as nothing:
print("suppress ->", nothing)
# Targets can be any assignment target, including a tuple.
with contextlib.nullcontext(("ORD-1002", 120.0)) as (order_id, total):
print(order_id, total)
# An exception still runs __exit__ and then propagates.
try:
with AuditedSession():
raise ValueError("bad order")
except ValueError as exc:
print("propagated:", exc)

Output:

enter: open audit session
exit: exc_type=None
{'user': 'agent-7', 'actions': ['viewed ORD-1001']}
open -> TextIOWrapper
Lock -> True
suppress -> None
ORD-1002 120.0
enter: open audit session
exit: exc_type=ValueError
propagated: bad order

A file object’s __enter__ returns the file itself, a lock’s returns True (the result of acquire()), and contextlib.suppress returns None. If you need the manager object, bind it before the with: lock = threading.Lock() then with lock:.

with A() as a, B() as b: is defined as two nested with statements: A is entered first and exited last. Since Python 3.10 the items can be wrapped in parentheses and split across lines, with an optional trailing comma, which removes the need for backslashes. Each as belongs to one item; there is no way to bind the whole group to one name. async with follows the same rules with __aenter__ and __aexit__, and is only valid inside an async def.

An OrdersPortal job exports shipped orders to CSV and marks them as exported in the same database transaction. It uses three managers: contextlib.closing to close the connection, the connection itself to commit or roll back, and the output file.

import csv
import os
import sqlite3
import tempfile
from contextlib import closing
export_path = os.path.join(tempfile.mkdtemp(), "shipped-orders.csv")
# Seed a throwaway OrdersPortal database.
with closing(sqlite3.connect(":memory:")) as db: # closes the connection
with db: # commits the transaction
db.execute("CREATE TABLE orders (id TEXT, email TEXT, total REAL, status TEXT)")
db.executemany("INSERT INTO orders VALUES (?, ?, ?, ?)", [
("ORD-3001", "ada@example.test", 59.90, "shipped"),
("ORD-3002", "lin@example.test", 120.00, "pending"),
("ORD-3003", "sam@example.test", 15.50, "shipped"),
])
# Python 3.10+: one with statement, several managers, one per line.
with (
db, # outer: commits only after the file is closed
open(export_path, "w", newline="", encoding="utf-8") as out,
):
writer = csv.writer(out)
writer.writerow(["order_id", "email", "total"])
rows = db.execute(
"SELECT id, email, total FROM orders WHERE status = 'shipped' ORDER BY id")
count = 0
for row in rows:
writer.writerow(row)
count += 1
db.execute("UPDATE orders SET status = 'exported' WHERE status = 'shipped'")
print(f"exported {count} orders")
print(db.execute("SELECT status, COUNT(*) FROM orders GROUP BY status ORDER BY status").fetchall())
with open(export_path, encoding="utf-8") as f:
print(f.read(), end="")
# After the outer block the connection is closed.
try:
db.execute("SELECT 1")
except sqlite3.ProgrammingError as exc:
print("ProgrammingError:", exc)

Output:

exported 2 orders
[('exported', 2), ('pending', 1)]
order_id,email,total
ORD-3001,ada@example.test,59.9
ORD-3003,sam@example.test,15.5
ProgrammingError: Cannot operate on a closed database.

Managers exit in reverse order, so the file is flushed and closed before the connection’s __exit__ commits. If writing a row or closing the file raises, the exception reaches the connection’s __exit__ first, which rolls back the UPDATE, so no order is marked as exported unless the file was written completely. The order of items in the with statement is therefore a design decision, not formatting.

import sqlite3
# 1. A tuple is not a context manager.
try:
with (open(__file__), open(__file__)) as files:
pass
except TypeError as exc:
print("TypeError:", exc)
# 2. Lazy reads after the block see a closed file.
def read_lines(path):
with open(path, encoding="utf-8") as f:
return (line.strip() for line in f) # generator escapes the block
try:
next(read_lines(__file__))
except ValueError as exc:
print("ValueError:", exc)
# 3. `with connection` manages the transaction, not the connection.
con = sqlite3.connect(":memory:")
with con as bound:
print("bound is con:", bound is con)
print("still usable:", con.execute("SELECT 1").fetchone())
con.close()

Output:

TypeError: 'tuple' object does not support the context manager protocol (missed __exit__ method)
ValueError: I/O operation on closed file.
bound is con: True
still usable: (1,)
  • Putting as after a parenthesized group. with (A(), B()) as x: builds a tuple and tries to enter it. Write as inside the parentheses, once per item. Python 3.11 and later raise TypeError for objects without the protocol (earlier versions raised AttributeError); the “(missed __exit__ method)” detail appears in 3.14 output but not in 3.11 to 3.13.
  • Returning a lazy iterator from inside the block. A generator over the file runs after __exit__ has closed it. Materialize the data (list(...)) inside the block, or make the caller own the with.
  • Assuming with sqlite3.connect(...) as con: closes the connection. The documentation is explicit: the connection’s context manager commits or rolls back but neither opens a new transaction nor closes the connection. Wrap it in contextlib.closing().
  • Assuming as binds the manager. with lock as l: gives True, not the lock. Keep a separate name for the manager.
  • Writing a @contextmanager generator without try/finally. If the block raises, the code after yield never runs, so cleanup or commit silently does not happen. Put cleanup in a finally clause.
  • Using the target after the block as if the resource were alive. The name survives, the resource usually does not: the file is closed and the lock released.
Situation Best tool
One resource with a clear lifetime (file, lock, transaction) with ... as
Two to four resources known in advance One with, parenthesized on 3.10+
A variable number of resources (open every file in a list) contextlib.ExitStack with enter_context()
Cleanup that must outlive the current function An object with an explicit close(), used through contextlib.closing by the caller
Asynchronous resources (connections, sessions) async with
Swallowing one expected exception contextlib.suppress, kept to the smallest possible block
Version Change
2.5 with statement (PEP 343), enabled with from __future__ import with_statement.
2.6 with always enabled and a reserved keyword.
3.1 Several context managers in one with statement.
3.5 async with (PEP 492).
3.10 Parenthesized, multi-line groups of context managers.
3.11 TypeError instead of AttributeError for objects that are not context managers.

1. In with open(path) as f:, why is f the file object? Is that always the case for with X as y? Because io file objects return self from __enter__. y is whatever __enter__ returns: a lock returns True, contextlib.suppress returns None, and a custom manager can return any object.

2. Does __exit__ run if __enter__ raises? No. The reference guarantees __exit__ only once __enter__ has returned without error. A manager that acquires two resources in __enter__ must clean up the first itself if acquiring the second fails, or use ExitStack internally.

3. What happens if __exit__ returns True? The exception raised in the block is suppressed and execution continues after the with statement. Returning a true value by accident (for example returning the result of a cleanup call) hides errors, which is why __exit__ usually returns None or False.

4. Senior scenario: OrdersPortal’s nightly export sometimes leaves “database is locked” errors and occasionally marks orders as exported that are missing from the file. The code is with open(path, "w") as out, sqlite3.connect(DB) as con:. What is wrong? Two problems. First, the connection is never closed: its context manager only commits or rolls back, so connections pile up and hold locks; wrap it in contextlib.closing. Second, the managers are in the wrong order. The connection is the inner manager, so the transaction commits before the outer file is flushed and closed; if the final flush fails (a full disk, for example), the orders are already marked as exported. Make the connection the outer manager so the commit happens only after the file closed cleanly. A file and a database still cannot commit atomically together, so for full safety write to a temporary file, close it, commit, then publish the file with os.replace, and make the export idempotent so a rerun after a crash between those steps is harmless.

  • with guarantees __exit__ runs once __enter__ has succeeded, on every exit path.
  • The as target gets __enter__’s return value, which is not always the manager.
  • Several managers in one statement nest left to right and exit in reverse; parenthesize them on Python 3.10+.
  • The target name stays bound after the block, but the resource behind it is usually closed.
  • Know what each manager actually manages: a sqlite3 connection’s with is a transaction, not a close.