28.7.contextlib — Utilities forwith-statement contexts¶

Source code:Lib/contextlib.py

This module provides utilities for common tasks involving thewithstatement. For more information see alsoContext Manager Types andWith Statement Context Managers.

Functions provided:

contextlib.contextmanager(func)¶

This function is adecorator that can be used to define a factoryfunction forwith statement context managers, without needing tocreate a class or separate__enter__() and__exit__() methods.

While many objects natively support use in with statements, sometimes aresource needs to be managed that isn’t a context manager in its own right,and doesn’t implement aclose() method for use withcontextlib.closing

An abstract example would be the following to ensure correct resourcemanagement:

fromcontextlibimportcontextmanager@contextmanagerdefmanaged_resource(*args,**kwds):# Code to acquire resource, e.g.:resource=acquire_resource(*args,**kwds)try:yieldresourcefinally:# Code to release resource, e.g.:release_resource(resource)>>>withmanaged_resource(timeout=3600)asresource:...# Resource is released at the end of this block,...# even if code in the block raises an exception

The function being decorated must return agenerator-iterator whencalled. This iterator must yield exactly one value, which will be bound tothe targets in thewith statement’sas clause, if any.

At the point where the generator yields, the block nested in thewithstatement is executed. The generator is then resumed after the block is exited.If an unhandled exception occurs in the block, it is reraised inside thegenerator at the point where the yield occurred. Thus, you can use atry…except…finally statement to trapthe error (if any), or ensure that some cleanup takes place. If an exception istrapped merely in order to log it or to perform some action (rather than tosuppress it entirely), the generator must reraise that exception. Otherwise thegenerator context manager will indicate to thewith statement thatthe exception has been handled, and execution will resume with the statementimmediately following thewith statement.

contextlib.nested(mgr1[,mgr2[,...]])¶

Combine multiple context managers into a single nested context manager.

This function has been deprecated in favour of the multiple manager formof thewith statement.

The one advantage of this function over the multiple manager form of thewith statement is that argument unpacking allows it to beused with a variable number of context managers as follows:

fromcontextlibimportnestedwithnested(*managers):do_something()

Note that if the__exit__() method of one of the nested context managersindicates an exception should be suppressed, no exception information will bepassed to any remaining outer context managers. Similarly, if the__exit__() method of one of the nested managers raises an exception, anyprevious exception state will be lost; the new exception will be passed to the__exit__() methods of any remaining outer context managers. In general,__exit__() methods should avoid raising exceptions, and in particular theyshould not re-raise a passed-in exception.

This function has two major quirks that have led to it being deprecated. Firstly,as the context managers are all constructed before the function is invoked, the__new__() and__init__() methods of the inner context managers arenot actually covered by the scope of the outer context managers. That means, forexample, that usingnested() to open two files is a programming error as thefirst file will not be closed promptly if an exception is thrown when openingthe second file.

Secondly, if the__enter__() method of one of the inner context managersraises an exception that is caught and suppressed by the__exit__() methodof one of the outer context managers, this construct will raiseRuntimeError rather than skipping the body of thewithstatement.

Developers that need to support nesting of a variable number of context managerscan either use thewarnings module to suppress the DeprecationWarningraised by this function or else use this function as a model for an applicationspecific implementation.

Deprecated since version 2.7:The with-statement now supports this functionality directly (without theconfusing error prone quirks).

contextlib.closing(thing)¶

Return a context manager that closesthing upon completion of the block. Thisis basically equivalent to:

fromcontextlibimportcontextmanager@contextmanagerdefclosing(thing):try:yieldthingfinally:thing.close()

And lets you write code like this:

fromcontextlibimportclosingimporturllibwithclosing(urllib.urlopen('http://www.python.org'))aspage:forlineinpage:printline

without needing to explicitly closepage. Even if an error occurs,page.close() will be called when thewith block is exited.