summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libcontextlib.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/lib/libcontextlib.tex')
-rw-r--r--Doc/lib/libcontextlib.tex130
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}