131 lines
3.8 KiB
TeX
131 lines
3.8 KiB
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}{contextmanager}{func}
|
|
This function is a decorator that can be used to define a factory
|
|
function for \keyword{with} statement context managers, without
|
|
needing to create a class or separate \method{__enter__()} and
|
|
\method{__exit__()} methods.
|
|
|
|
A simple example (this is not recommended as a real way of
|
|
generating HTML!):
|
|
|
|
\begin{verbatim}
|
|
from __future__ import with_statement
|
|
from contextlib import contextmanager
|
|
|
|
@contextmanager
|
|
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 generator context manager will
|
|
indicate to the \keyword{with} statement that the exception has been
|
|
handled, and execution will resume with the statement immediately
|
|
following 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 nested
|
|
context managers indicates an exception should be suppressed, no
|
|
exception information will be passed to any remaining outer context
|
|
managers. Similarly, if the \method{__exit__()} method of one of the
|
|
nested managers 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 managers.
|
|
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 manager that closes \var{thing} upon completion of
|
|
the block. This is basically equivalent to:
|
|
|
|
\begin{verbatim}
|
|
from contextlib import contextmanager
|
|
|
|
@contextmanager
|
|
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.
|
|
\end{funcdesc}
|
|
|
|
\begin{seealso}
|
|
\seepep{0343}{The "with" statement}
|
|
{The specification, background, and examples for the
|
|
Python \keyword{with} statement.}
|
|
\end{seealso}
|