From 168e99f6db1a207477fa02609663b66475bfd460 Mon Sep 17 00:00:00 2001
From: "Phillip J. Eby" <pje@telecommunity.com>
Date: Tue, 28 Mar 2006 00:13:10 +0000
Subject: Document objects that can be used with the ``with`` statement.

---
 Doc/lib/libdecimal.tex   | 28 ++++++++++++++++++++++++++--
 Doc/lib/libstdtypes.tex  | 32 ++++++++++++++++++++++++++++++++
 Doc/lib/libthread.tex    | 13 +++++++++++++
 Doc/lib/libthreading.tex | 23 +++++++++++++++++++++++
 4 files changed, 94 insertions(+), 2 deletions(-)

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 @@ the \function{getcontext()} and \function{setcontext()} functions:
   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 @@ Files have the following methods:
   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 4914948d..9e0c202 100644
--- a/Doc/lib/libthread.tex
+++ b/Doc/lib/libthread.tex
@@ -100,6 +100,19 @@ Return the status of the lock:\ \code{True} if it has been acquired by
 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 @@ keyword arguments \var{kwargs}, after \var{interval} seconds have passed.
 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}
+
-- 
cgit v0.12