[Python-checkins] r43369 - python/trunk/Doc/lib/libdecimal.tex python/trunk/Doc/lib/libstdtypes.tex python/trunk/Doc/lib/libthread.tex python/trunk/Doc/lib/libthreading.tex

Tue Mar 28 02:13:13 CEST 2006

Author: phillip.eby
Date: Tue Mar 28 02:13:10 2006
New Revision: 43369
Modified:
 python/trunk/Doc/lib/libdecimal.tex
 python/trunk/Doc/lib/libstdtypes.tex
 python/trunk/Doc/lib/libthread.tex
 python/trunk/Doc/lib/libthreading.tex
Log:
Document objects that can be used with the ``with`` statement.
Modified: python/trunk/Doc/lib/libdecimal.tex
==============================================================================

--- python/trunk/Doc/lib/libdecimal.tex	(original)
+++ python/trunk/Doc/lib/libdecimal.tex	Tue Mar 28 02:13:10 2006
@@ -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
Modified: python/trunk/Doc/lib/libstdtypes.tex
==============================================================================
--- python/trunk/Doc/lib/libstdtypes.tex	(original)
+++ python/trunk/Doc/lib/libstdtypes.tex	Tue Mar 28 02:13:10 2006
@@ -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}{}
Modified: python/trunk/Doc/lib/libthread.tex
==============================================================================
--- python/trunk/Doc/lib/libthread.tex	(original)
+++ python/trunk/Doc/lib/libthread.tex	Tue Mar 28 02:13:10 2006
@@ -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}
Modified: python/trunk/Doc/lib/libthreading.tex
==============================================================================
--- python/trunk/Doc/lib/libthreading.tex	(original)
+++ python/trunk/Doc/lib/libthreading.tex	Tue Mar 28 02:13:10 2006
@@ -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}
+
