\section{\module{contextlib} ---         Utilities for \keyword{with}-statement contexts.} \declaremodule{standard}{contextlib}\modulesynopsis{Utilities for \keyword{with}-statement contexts.} \versionadded{2.5} This module provides utilities for common tasks involving the\keyword{with} statement. Functions provided: \begin{funcdesc}{contextmanager}{func}This function is a decorator that can be used to define a factoryfunction for \keyword{with} statement context managers, withoutneeding to create a class or separate \method{__enter__()} and\method{__exit__()} methods. A simple example (this is not recommended as a real way ofgenerating HTML!): \begin{verbatim}from __future__ import with_statementfrom contextlib import contextmanager @contextmanagerdef tag(name):    print "<%s>" % name    yield    print "</%s>" % name >>> with tag("h1"):...    print "foo"...<h1>foo</h1>\end{verbatim} The function being decorated must return a generator-iterator whencalled. This iterator must yield exactly one value, which will bebound to the targets in the \keyword{with} statement's \keyword{as}clause, if any. At the point where the generator yields, the block nested in the\keyword{with} statement is executed.  The generator is then resumedafter the block is exited.  If an unhandled exception occurs in theblock, it is reraised inside the generator at the point where the yieldoccurred.  Thus, you can use a\keyword{try}...\keyword{except}...\keyword{finally} statement to trapthe error (if any), or ensure that some cleanup takes place. If anexception is trapped merely in order to log it or to perform someaction (rather than to suppress it entirely), the generator mustreraise that exception. Otherwise the generator context manager willindicate to the \keyword{with} statement that the exception has beenhandled, and execution will resume with the statement immediatelyfollowing the \keyword{with} statement.\end{funcdesc} \begin{funcdesc}{nested}{mgr1\optional{, mgr2\optional{, ...}}}Combine multiple context managers into a single nested context manager. Code like this: \begin{verbatim}from contextlib import nested with nested(A, B, C) as (X, Y, Z):    do_something()\end{verbatim} is equivalent to this: \begin{verbatim}with A as X:    with B as Y:        with C as Z:            do_something()\end{verbatim} Note that if the \method{__exit__()} method of one of the nestedcontext managers indicates an exception should be suppressed, noexception information will be passed to any remaining outer contextmanagers. Similarly, if the \method{__exit__()} method of one of thenested managers raises an exception, any previous exception state willbe lost; the new exception will be passed to the\method{__exit__()} methods of any remaining outer context managers.In general, \method{__exit__()} methods should avoid raisingexceptions, and in particular they should not re-raise apassed-in exception.\end{funcdesc} \label{context-closing}\begin{funcdesc}{closing}{thing}Return a context manager that closes \var{thing} upon completion ofthe block.  This is basically equivalent to: \begin{verbatim}from contextlib import contextmanager @contextmanagerdef closing(thing):    try:        yield thing    finally:        thing.close()\end{verbatim} And lets you write code like this:\begin{verbatim}from __future__ import with_statementfrom contextlib import closingimport codecs with closing(urllib.urlopen('http://www.python.org')) as page:    for line in page:        print line\end{verbatim} without needing to explicitly close \code{page}.  Even if an erroroccurs, \code{page.close()} will be called when the \keyword{with}block is exited.\end{funcdesc} \begin{seealso}  \seepep{0343}{The "with" statement}         {The specification, background, and examples for the          Python \keyword{with} statement.}\end{seealso}