Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager()

4 files changed, 56 insertions, 76 deletions

diff --git a/Doc/lib/libcontextlib.tex b/Doc/lib/libcontextlib.tex
index 6c80a71..f28bdd0 100644
--- a/Doc/lib/libcontextlib.tex
+++ b/Doc/lib/libcontextlib.tex
@@ -11,19 +11,20 @@ This module provides utilities for common tasks involving the
 
 Functions provided:
 
-\begin{funcdesc}{context}{func}
+\begin{funcdesc}{contextmanager}{func}
 This function is a decorator that can be used to define a factory
 function for \keyword{with} statement context objects, without
 needing to create a class or separate \method{__enter__()} and
 \method{__exit__()} methods.
 
-A simple example:
+A simple example (this is not recommended as a real way of
+generating HTML!):
 
 \begin{verbatim}
 from __future__ import with_statement
-from contextlib import contextfactory
+from contextlib import contextmanager
 
-@contextfactory
+@contextmanager
 def tag(name):
     print "<%s>" % name
     yield
@@ -56,7 +57,7 @@ treat the exception as having been handled, and resume execution with
 the statement immediately following the \keyword{with} statement.
 \end{funcdesc}
 
-\begin{funcdesc}{nested}{ctx1\optional{, ctx2\optional{, ...}}}
+\begin{funcdesc}{nested}{mgr1\optional{, mgr2\optional{, ...}}}
 Combine multiple context managers into a single nested context manager.
 
 Code like this:
@@ -78,12 +79,12 @@ with A as X:
 \end{verbatim}
 
 Note that if the \method{__exit__()} method of one of the nested
-context objects indicates an exception should be suppressed, no
+context managers indicates an exception should be suppressed, no
 exception information will be passed to any remaining outer context
 objects. Similarly, if the \method{__exit__()} method of one of the
-nested context objects raises an exception, any previous exception
+nested context 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 objects.
+\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.
@@ -91,13 +92,13 @@ passed-in exception.
 
 \label{context-closing}
 \begin{funcdesc}{closing}{thing}
-Return a context that closes \var{thing} upon completion of the
-block.  This is basically equivalent to:
+Return a context manager that closes \var{thing} upon completion of
+the block.  This is basically equivalent to:
 
 \begin{verbatim}
-from contextlib import contextfactory
+from contextlib import contextmanager
 
-@contextfactory
+@contextmanager
 def closing(thing):
     try:
         yield thing
diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index cd9f7d4..d05b075 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -1753,67 +1753,50 @@ implemented in C will have to provide a writable
 \end{memberdesc}
 
 
-\subsection{Context Types \label{typecontext}}
+\subsection{Context Manager Types \label{typecontextmanager}}
 
 \versionadded{2.5}
-\index{with statement context protocol}
+\index{context manager}
 \index{context management protocol}
-\index{protocol!with statement context}
 \index{protocol!context management}
 
 Python's \keyword{with} statement supports the concept of a runtime
 context defined by a context manager.  This is implemented using
-three distinct methods; these are used to allow user-defined
-classes to define a runtime context.
+two separate methods that allow user-defined classes to define
+a runtime context that is entered before the statement body is
+executed and exited when the statement ends.
 
-The \dfn{context management protocol} consists of a single
-method that needs to be provided for a context manager object to
+The \dfn{context management protocol} consists of a pair of
+methods that need to be provided for a context manager object to
 define a runtime context:
 
-\begin{methoddesc}[context manager]{__context__}{}
-  Return a with statement context object.  The object is required to
-  support the with statement context protocol described below.  If an
-  object supports different kinds of runtime context, additional
-  methods can be provided to specifically request context objects for
-  those kinds of runtime context.  (An example of an object supporting
-  multiple kinds of context would be a synchronisation object which
-  supported both a locked context for normal thread synchronisation
-  and an unlocked context to temporarily release a held lock while
-  performing a potentially long running operation)
-\end{methoddesc}
-
-The with statement context objects themselves are required to support the
-following three methods, which together form the
-\dfn{with statement context protocol}:
+\begin{methoddesc}[context manager]{__enter__}{}
+  Enter the runtime context and return either this object or another
+  object related to the runtime context. The value returned by this
+  method is bound to the identifier in the \keyword{as} clause of
+  \keyword{with} statements using this context manager.
 
-\begin{methoddesc}[with statement context]{__context__}{}
-  Return the context object itself.  This is required to allow both
-  context objects and context managers to be used in a \keyword{with}
+  An example of a context manager that returns itself is a file object.
+  File objects return themselves from __enter__() to allow
+  \function{open()} to be used as the context expression in a with
   statement.
-\end{methoddesc}
 
-\begin{methoddesc}[with statement context]{__enter__}{}
-  Enter the runtime context and return either the defining context
-  manager or another object related to the runtime context. The value
-  returned by this method is bound to the identifier in the
-  \keyword{as} clause of \keyword{with} statements using this context.
-  (An example of a context object that returns the original context
-  manager is file objects, which are returned from __enter__() to
-  allow \function{open()} to be used directly in a with
-  statement. An example of a context object that returns a related
-  object is \code{decimal.Context} which sets the active decimal
-  context to a copy of the context manager and then returns the copy.
-  This allows changes to be made to the current decimal context in the
-  body of the \keyword{with} statement without affecting code outside
-  the \keyword{with} statement).
+  An example of a context manager that returns a related
+  object is the one returned by \code{decimal.Context.get_manager()}.
+  These managers set the active decimal context to a copy of the
+  original decimal context and then return the copy. This allows
+  changes to be made to the current decimal context in the body of
+  the \keyword{with} statement without affecting code outside
+  the \keyword{with} statement.
 \end{methoddesc}
 
-\begin{methoddesc}[with statement context]{__exit__}{exc_type, exc_val, exc_tb}
+\begin{methoddesc}[context manager]{__exit__}{exc_type, exc_val, exc_tb}
   Exit the runtime context and return a Boolean flag indicating if any
   expection that occurred should be suppressed. If an exception
   occurred while executing the body of the \keyword{with} statement, the
   arguments contain the exception type, value and traceback information.
   Otherwise, all three arguments are \var{None}.
+
   Returning a true value from this method will cause the \keyword{with}
   statement to suppress the exception and continue execution with the
   statement immediately following the \keyword{with} statement. Otherwise
@@ -1821,6 +1804,7 @@ following three methods, which together form the
   executing. Exceptions that occur during execution of this method will
   replace any exception that occurred in the body of the \keyword{with}
   statement.
+
   The exception passed in should never be reraised explicitly - instead,
   this method should return a false value to indicate that the method
   completed successfully and does not want to suppress the raised
@@ -1829,20 +1813,18 @@ following three methods, which together form the
   \method{__exit__()} method has actually failed.
 \end{methoddesc}
 
-Python defines several context objects and managers to support
-easy thread synchronisation, prompt closure of files or other
-objects, and thread-safe manipulation of the decimal arithmetic
-context. The specific types are not important beyond their
-implementation of the context management and with statement context
-protocols.
+Python defines several context managers to support easy thread
+synchronisation, prompt closure of files or other objects, and
+simpler manipulation of the active decimal arithmetic
+context. The specific types are not treated specially beyond
+their implementation of the context management protocol.
 
 Python's generators and the \code{contextlib.contextfactory} decorator
-provide a convenient way to implement these protocols.  If a context
-manager's \method{__context__()} method is implemented as a
-generator decorated with the \code{contextlib.contextfactory}
-decorator, it will automatically return a with statement context
-object supplying the necessary \method{__context__()},
-\method{__enter__()} and \method{__exit__()} methods.
+provide a convenient way to implement these protocols.  If a generator
+function is decorated with the \code{contextlib.contextfactory}
+decorator, it will return a context manager implementing the necessary
+\method{__enter__()} and \method{__exit__()} methods, rather than the
+iterator produced by an undecorated generator function.
 
 Note that there is no specific slot for any of these methods in the
 type structure for Python objects in the Python/C API. Extension
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index a756e30..296f79f 100644
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -2112,14 +2112,13 @@ implement a \method{__coerce__()} method, for use by the built-in
 
 \end{itemize}
 
-\subsection{With Statement Contexts and Context Managers\label{context-managers}}
+\subsection{With Statement Context Managers\label{context-managers}}
 
 \versionadded{2.5}
 
 A \dfn{context manager} is an object that defines the runtime
 context to be established when executing a \keyword{with}
-statement. The context manager provides a
-\dfn{with statement context object} which manages the entry into,
+statement. The context manager handles 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
@@ -2127,18 +2126,16 @@ can also be used by directly invoking their methods.
 
 \stindex{with}
 \index{context manager}
-\index{context (with statement)}
-\index{with statement context}
 
-Typical uses of context managers and contexts include saving and
+Typical uses of context managers include saving and
 restoring various kinds of global state, locking and unlocking
 resources, closing opened files, etc.
 
-For more information on context managers and context objects,
-see ``\ulink{Context Types}{../lib/typecontext.html}'' in the
+For more information on context managers, see
+``\ulink{Context Types}{../lib/typecontextmanager.html}'' in the
 \citetitle[../lib/lib.html]{Python Library Reference}.
 
-\begin{methoddesc}[with statement context]{__enter__}{self}
+\begin{methoddesc}[context manager]{__enter__}{self}
 Enter the runtime context related to 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.
diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex
index 4a23133..b213cb2 100644
--- a/Doc/ref/ref7.tex
+++ b/Doc/ref/ref7.tex
@@ -315,8 +315,8 @@ statement to generate exceptions may be found in section~\ref{raise}.
 \versionadded{2.5}
 
 The \keyword{with} statement is used to wrap the execution of a block
-with methods defined by a context manager or \keyword{with} statement context
-object (see section~\ref{context-managers}). This allows common
+with methods defined by a context manager (see
+section~\ref{context-managers}). This allows common
 \keyword{try}...\keyword{except}...\keyword{finally} usage patterns to
 be encapsulated for convenient reuse.