diff options
Diffstat (limited to 'Doc/lib/libcontextlib.tex')
-rw-r--r-- | Doc/lib/libcontextlib.tex | 130 |
1 files changed, 0 insertions, 130 deletions
diff --git a/Doc/lib/libcontextlib.tex b/Doc/lib/libcontextlib.tex deleted file mode 100644 index 0ac5442..0000000 --- a/Doc/lib/libcontextlib.tex +++ /dev/null @@ -1,130 +0,0 @@ -\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 urllib - -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} |