Doc/lib/libcontextlib.tex

\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}{context}{func}
This function is a decorator that can be used to define a factory
function for \keyword{with} statement context objects, without
needing to create a class or separate \method{__enter__()} and
\method{__exit__()} methods.

A simple example:

\begin{verbatim}
from __future__ import with_statement
from contextlib import contextfactory

@contextfactory
def 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 when
called. This iterator must yield exactly one value, which will be
bound 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 resumed
after the block is exited.  If an unhandled exception occurs in the
block, it is reraised inside the generator at the point where the yield
occurred.  Thus, you can use a
\keyword{try}...\keyword{except}...\keyword{finally} statement to trap
the error (if any), or ensure that some cleanup takes place. If an
exception is trapped merely in order to log it or to perform some
action (rather than to suppress it entirely), the generator must
reraise that exception. Otherwise the \keyword{with} statement will
treat the exception as having been handled, and resume execution with
the statement immediately following the \keyword{with} statement.

Note that you can use \code{@contextfactory} to define a context
manager's \method{__context__} method.  This is usually more
convenient than creating another class just to serve as a context
object. For example:

\begin{verbatim}
from __future__ import with_statement
from contextlib import contextfactory

class Tag:
    def __init__(self, name):
        self.name = name
        
    @contextfactory
    def __context__(self):
        print "<%s>" % self.name
        yield self
        print "</%s>" % self.name
        
h1 = Tag("h1")

>>> with h1 as me:
...     print "hello from", me
<h1>
hello from <__main__.Tag instance at 0x402ce8ec>
</h1>
\end{verbatim}
\end{funcdesc}

\begin{funcdesc}{nested}{ctx1\optional{, ctx2\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 nested
context objects indicates an exception should be suppressed, no
exception information will be passed to any remaining outer context
objects. Similarly, if the \method{__exit__()} method of one of the
nested context objects raises an exception, any previous exception
state will be lost; the new exception will be passed to the
\method{__exit__()} methods of any remaining outer context objects.
In general, \method{__exit__()} methods should avoid raising
exceptions, and in particular they should not re-raise a
passed-in exception.
\end{funcdesc}

\label{context-closing}
\begin{funcdesc}{closing}{thing}
Return a context that closes \var{thing} upon completion of the
block.  This is basically equivalent to:

\begin{verbatim}
from contextlib import contextfactory

@contextfactory
def closing(thing):
    try:
        yield thing
    finally:
        thing.close()
\end{verbatim}

And lets you write code like this:
\begin{verbatim}
from __future__ import with_statement
from contextlib import closing
import 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 error
occurs, \code{page.close()} will be called when the \keyword{with}
block is exited.

Context managers with a close method can use this context factory
directly without needing to implement their own
\method{__context__()} method.
\begin{verbatim}
from __future__ import with_statement
from contextlib import closing

class MyClass:
    def close(self):
        print "Closing", self
    __context__ = closing

>>> with MyClass() as x:
...     print "Hello from", x
...
Hello from <__main__.MyClass instance at 0xb7df02ec>
Closing <__main__.MyClass instance at 0xb7df02ec>
\end{verbatim}
\end{funcdesc}

\begin{seealso}
  \seepep{0343}{The "with" statement}
         {The specification, background, and examples for the
          Python \keyword{with} statement.}
\end{seealso}