add hg and python

1 files changed, 130 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libcontextlib.tex b/sys/src/cmd/python/Doc/lib/libcontextlib.tex
new file mode 100644
index 000000000..72bf53716
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libcontextlib.tex
@@ -0,0 +1,130 @@
+\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}