Update with statement documentation to use same terminology as 2.5a1 implementation

diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index 964013f816ed4b5b12193ed50ca0205ccf134a47..b59f937bf20b6b7dbbfbac8f62408dbfd000df9f 100644 (file)
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -2116,42 +2116,54 @@ implement a \method{__coerce__()} method, for use by the built-in
 
 \versionadded{2.5}
 
-A \dfn{context manager} is an object that manages the entry to, and exit
-from, a \dfn{context} surrounding a block of code.  Context managers are
-normally invoked using the \keyword{with} statement (described in
-section~\ref{with}), but can also be used by directly invoking their
-methods.
+A \dfn{context object} is an object that defines the runtime context
+to be established when executing a \keyword{with} statement. The
+context object provides a \dfn{context manager} which manages the
+entry into, and the exit from, the desired runtime context for the
+execution of the block of code.  Context managers are normally
+invoked using the \keyword{with} statement (described in
+section~\ref{with}), but can also be used by directly invoking
+their methods.
+
 \stindex{with}
 \index{context manager}
-\index{context}
+\index{context object}
 
-Typical uses of context managers include saving and restoring various
-kinds of global state, locking and unlocking resources, closing opened
-files, etc.
+Typical uses of contexts and context managers include saving and
+restoring various kinds of global state, locking and unlocking
+resources, closing opened files, etc.
 
-\begin{methoddesc}[context manager]{__context__}{self}
+For more information on contexts and context manager objects, see
+``\ulink{Context Types}{../lib/typecontext.html}'' in the
+\citetitle[../lib/lib.html]{Python Library Reference}.
+
+\begin{methoddesc}[context]{__context__}{self}
 Invoked when the object is used as the context expression of a
 \keyword{with} statement.  The return value must implement
-\method{__enter__()} and \method{__exit__()} methods.  Simple context
-managers that wish to directly
-implement \method{__enter__()} and \method{__exit__()} should just
-return \var{self}.
+\method{__enter__()} and \method{__exit__()} methods.  Simple contexts
+may be able to implement \method{__enter__()} and \method{__exit__()}
+directly without requiring a separate context manager object and
+should just return \var{self}.
 
-Context managers written in Python can also implement this method using
+Context objects written in Python can also implement this method using
 a generator function decorated with the
 \function{contextlib.contextmanager} decorator, as this can be simpler
 than writing individual \method{__enter__()} and \method{__exit__()}
-methods when the state to be managed is complex.
+methods on a separate object when the state to be managed is complex.
+
+Context manager objects also need to implement this method; they are
+required to return themselves.
 \end{methoddesc}
 
-\begin{methoddesc}[context]{__enter__}{self}
-Enter the context defined by this object. The \keyword{with} statement
+\begin{methoddesc}[context manager]{__enter__}{self}
+Enter the context managed by this object. The \keyword{with} statement
 will bind this method's return value to the target(s) specified in the
 \keyword{as} clause of the statement, if any.
 \end{methoddesc}
 
-\begin{methoddesc}[context]{__exit__}{exc_type, exc_value, traceback}
-Exit the context defined by this object. The parameters describe the
+\begin{methoddesc}[context manager]{__exit__}
+{self, exc_type, exc_value, traceback}
+Exit the context managed by this object. The parameters describe the
 exception that caused the context to be exited. If the context was
 exited without an exception, all three arguments will be
 \constant{None}.

diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex
index ecbc75614a9aac9fc6f93947b2026e21bb803876..d7929af201de3fb9541c105fd534bc153c8ecb9c 100644 (file)
--- a/Doc/ref/ref7.tex
+++ b/Doc/ref/ref7.tex
@@ -329,13 +329,12 @@ The execution of the \keyword{with} statement proceeds as follows:
 
 \begin{enumerate}
 
-\item The expression is evaluated, to obtain a context manager
-object.
+\item The expression is evaluated, to obtain a context object.
 
-\item The context manager's \method{__context__()} method is invoked to
-obtain a context object.
+\item The context object's \method{__context__()} method is invoked to
+obtain a context manager object.
 
-\item The context object's \method{__enter__()} method is invoked.
+\item The context manager's \method{__enter__()} method is invoked.
 
 \item If a target list was included in the \keyword{with}
 statement, the return value from \method{__enter__()} is assigned to it.
@@ -348,8 +347,8 @@ an error occurring within the suite would be. See step 6 below.}
 
 \item The suite is executed.
 
-\item The context object's \method{__exit__()} method is invoked. If an
-exception caused the suite to be exited, its type, value, and
+\item The context manager's \method{__exit__()} method is invoked. If
+an exception caused the suite to be exited, its type, value, and
 traceback are passed as arguments to \method{__exit__()}. Otherwise,
 three \constant{None} arguments are supplied.