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()
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 @@
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 @@
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 @@
\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 @@
\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 @@
\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}
+\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.
-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}[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.
+
+ 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]{__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).
-\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 @@
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 @@
\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