Document objects that can be used with the ``with`` statement.
diff --git a/Doc/lib/libdecimal.tex b/Doc/lib/libdecimal.tex
index 092f038..ffc3363 100644
--- a/Doc/lib/libdecimal.tex
+++ b/Doc/lib/libdecimal.tex
@@ -442,9 +442,33 @@
Set the current context for the active thread to \var{c}.
\end{funcdesc}
-New contexts can formed using the \class{Context} constructor described below.
-In addition, the module provides three pre-made contexts:
+Beginning with Python 2.5, you can also use the \keyword{with} statement
+to temporarily change the active context. For example the following code
+increases the current decimal precision by 2 places, performs a
+calculation, and then automatically restores the previous context:
+\begin{verbatim}
+from __future__ import with_statement
+import decimal
+
+with decimal.getcontext() as ctx:
+ ctx.prec += 2 # add 2 more digits of precision
+ calculate_something()
+\end{verbatim}
+
+The context that's active in the body of the \keyword{with} statement is
+a \emph{copy} of the context you provided to the \keyword{with}
+statement, so modifying its attributes doesn't affect anything except
+that temporary copy.
+
+You can use any decimal context in a \keyword{with} statement, but if
+you just want to make a temporary change to some aspect of the current
+context, it's easiest to just use \function{getcontext()} as shown
+above.
+
+New contexts can also be created using the \class{Context} constructor
+described below. In addition, the module provides three pre-made
+contexts:
\begin{classdesc*}{BasicContext}
This is a standard context defined by the General Decimal Arithmetic
diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index a1fa6f0..017b080 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -1500,6 +1500,38 @@
Any operation which requires that the file be open will raise a
\exception{ValueError} after the file has been closed. Calling
\method{close()} more than once is allowed.
+
+ As of Python 2.5, you can avoid having to call this method explicitly
+ if you use the \keyword{with} statement. For example, the following
+ code will automatically close \code{f} when the \keyword{with} block
+ is exited:
+
+\begin{verbatim}
+from __future__ import with_statement
+
+with open("hello.txt") as f:
+ for line in f:
+ print line
+\end{verbatim}
+
+ In older versions of Python, you would have needed to do this to get
+ the same effect:
+
+\begin{verbatim}
+f = open("hello.txt")
+try:
+ for line in f:
+ print line
+finally:
+ f.close()
+\end{verbatim}
+
+ \note{Not all ``file-like'' types in Python support use as a context
+ manager for the \keyword{with} statement. If your code is intended to
+ work with any file-like object, you can use the \function{closing()}
+ function in the \module{contextlib} module instead of using the object
+ directly. See section~\ref{context-closing} for details.}
+
\end{methoddesc}
\begin{methoddesc}[file]{flush}{}
diff --git a/Doc/lib/libthread.tex b/Doc/lib/libthread.tex
index 4914948..9e0c202 100644
--- a/Doc/lib/libthread.tex
+++ b/Doc/lib/libthread.tex
@@ -100,6 +100,19 @@
some thread, \code{False} if not.
\end{methoddesc}
+In addition to these methods, lock objects can also be used via the
+\keyword{with} statement, e.g.:
+
+\begin{verbatim}
+from __future__ import with_statement
+import thread
+
+a_lock = thread.allocate_lock()
+
+with a_lock:
+ print "a_lock is locked while this executes"
+\end{verbatim}
+
\strong{Caveats:}
\begin{itemize}
diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex
index 33839a4..8fb3137 100644
--- a/Doc/lib/libthreading.tex
+++ b/Doc/lib/libthreading.tex
@@ -675,3 +675,26 @@
Stop the timer, and cancel the execution of the timer's action. This
will only work if the timer is still in its waiting stage.
\end{methoddesc}
+
+\subsection{Using locks, conditions, and semaphores in the \keyword{with}
+statement \label{with-locks}}
+
+All of the objects provided by this module that have \method{acquire()} and
+\method{release()} methods can be used as context managers for a \keyword{with}
+statement. The \method{acquire()} method will be called when the block is
+entered, and \method{release()} will be called when the block is exited.
+
+Currently, \class{Lock}, \class{RLock}, \class{Condition}, \class{Semaphore},
+and \class{BoundedSemaphore} objects may be used as \keyword{with}
+statement context managers. For example:
+
+\begin{verbatim}
+from __future__ import with_statement
+import threading
+
+some_rlock = threading.RLock()
+
+with some_rlock:
+ print "some_rlock is locked while this executes"
+\end{verbatim}
+