Python with ... as: Reliable Cleanup (PEP 343)
What you’ll learn
Section titled “What you’ll learn”- What the
withstatement guarantees, and the exacttry/finallycode it replaces. - What the
astarget 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
sqlite3connections that stay open.
Summary
Section titled “Summary”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.
The problem it solves
Section titled “The problem it solves”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 osimport 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: TrueHow it works
Section titled “How it works”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 SUITEexcept: hit_except = True if not exit(*sys.exc_info()): raisefinally: if not hit_except: exit(None, None, None)Four consequences follow directly from that expansion:
TARGETreceivesenter()’s return value. Many managers returnself, but not all do.__exit__runs only if__enter__succeeded. If__enter__raises, there is nothing to clean up and the exception propagates.__exit__decides whether an exception propagates. A true return value suppresses it; a false one (includingNone) re-raises it.- The
asname is an ordinary assignment. It stays bound after the block. This differs fromexcept E as name, where the name is deleted at the end of the clause.
import contextlibimport 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 sessionexit: exc_type=None{'user': 'agent-7', 'actions': ['viewed ORD-1001']}open -> TextIOWrapperLock -> Truesuppress -> NoneORD-1002 120.0enter: open audit sessionexit: exc_type=ValueErrorpropagated: bad orderA 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:.
Several managers in one statement
Section titled “Several managers in one statement”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.
Realistic example
Section titled “Realistic example”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 csvimport osimport sqlite3import tempfilefrom 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,totalORD-3001,ada@example.test,59.9ORD-3003,sam@example.test,15.5ProgrammingError: 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.
Common mistakes
Section titled “Common mistakes”import sqlite3
# 1. A tuple is not a context manager.try: with (open(__file__), open(__file__)) as files: passexcept 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: Truestill usable: (1,)- Putting
asafter a parenthesized group.with (A(), B()) as x:builds a tuple and tries to enter it. Writeasinside the parentheses, once per item. Python 3.11 and later raiseTypeErrorfor objects without the protocol (earlier versions raisedAttributeError); 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 thewith. - 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 incontextlib.closing(). - Assuming
asbinds the manager.with lock as l:givesTrue, not the lock. Keep a separate name for the manager. - Writing a
@contextmanagergenerator withouttry/finally. If the block raises, the code afteryieldnever runs, so cleanup or commit silently does not happen. Put cleanup in afinallyclause. - 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.
When to use it and when not to
Section titled “When to use it and when not to”| 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 |
Compatibility
Section titled “Compatibility”| 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. |
Interview questions
Section titled “Interview questions”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.
Key takeaways
Section titled “Key takeaways”withguarantees__exit__runs once__enter__has succeeded, on every exit path.- The
astarget 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
sqlite3connection’swithis a transaction, not a close.
Related pages
Section titled “Related pages”- Context managers: writing managers with
__enter__/__exit__andcontextlib. - Context managers tutorial: a step-by-step introduction.
- File I/O: reading and writing files with
with open(...). - Error handling:
try,except,finallyand exception chaining. - async/await: coroutines and
async with. - raise … from: chaining exceptions raised during cleanup.
Official references
Section titled “Official references”- The with statement (Python 3.14 language reference)
- With statement context managers (Python 3.14 data model)
- contextlib (Python 3.14 docs)
- sqlite3: how to use the connection context manager (Python 3.14 docs)
- What’s New in Python 3.10: parenthesized context managers
- What’s New in Python 3.11
- PEP 343: The “with” Statement