Change PEP 343 related documentation to use the term context specifier instead of context object

Doc/lib/libcontextlib.tex

@@ -46,12 +46,17 @@ after the block is exited.  If an unhandled exception occurs in the
 block, it is reraised inside the generator at the point where the yield
 occurred.  Thus, you can use a
 \keyword{try}...\keyword{except}...\keyword{finally} statement to trap
-the error (if any), or ensure that some cleanup takes place.
+the error (if any), or ensure that some cleanup takes place. If an
+exception is trapped merely in order to log it or to perform some
+action (rather than to suppress it entirely), the generator must
+reraise that exception. Otherwise the \keyword{with} statement will
+treat the exception as having been handled, and resume execution with
+the statement immediately following the \keyword{with} statement.
 
 Note that you can use \code{@contextmanager} to define a context
-object's \method{__context__} method.  This is usually more convenient
-than creating another class just to serve as a context manager.
-For example:
+specifier's \method{__context__} method.  This is usually more
+convenient than creating another class just to serve as a context
+manager. For example:
 
 \begin{verbatim}
 from __future__ import with_statement
@@ -78,7 +83,7 @@ hello from <__main__.Tag instance at 0x402ce8ec>
 \end{funcdesc}
 
 \begin{funcdesc}{nested}{ctx1\optional{, ctx2\optional{, ...}}}
-Combine multiple context managers into a single nested context manager.
+Combine multiple context specifiers into a single nested context manager.
 
 Code like this:
 
@@ -98,11 +103,15 @@ with A as X:
             do_something()
 \end{verbatim}
 
-Note that if the \method{__exit__()} method of one of the 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 managers.  In general, \method{__exit__()} methods should avoid
-raising exceptions, and in particular they should not re-raise a
+Note that if the \method{__exit__()} method of one of the nested
+context managers indicates an exception should be suppressed, no
+exception information will be passed to any remaining outer context
+managers. Similarly, if the \method{__exit__()} method of one of the
+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 managers.
+In general, \method{__exit__()} methods should avoid raising
+exceptions, and in particular they should not re-raise a
 passed-in exception.
 \end{funcdesc}
 

Doc/lib/libstdtypes.tex

@@ -1756,20 +1756,21 @@ implemented in C will have to provide a writable
 \subsection{Context Types \label{typecontext}}
 
 \versionadded{2.5}
-\index{context protocol}
+\index{context specification protocol}
 \index{context management protocol}
-\index{protocol!context}
+\index{protocol!context specification}
 \index{protocol!context management}
 
 Python's \keyword{with} statement supports the concept of a runtime
-context defined by a context object.  This is implemented using three
-distinct methods; these are used to allow user-defined classes to
-define a context.
+context defined by a context specifier.  This is implemented using
+three distinct methods; these are used to allow user-defined
+classes to define a context.
 
-The \dfn{context protocol} consists of a single method that needs
-to be provided for an object to define a runtime context:
+The \dfn{context specification protocol} consists of a single
+method that needs to be provided for a context specifier object to
+define a runtime context:
 
-\begin{methoddesc}[context]{__context__}{}
+\begin{methoddesc}[context specifier]{__context__}{}
   Return a context manager object.  The object is required to support
   the context management protocol described below.  If an object
   supports different kinds of runtime context, additional methods can
@@ -1787,27 +1788,29 @@ following three methods, which together form the
 
 \begin{methoddesc}[context manager]{__context__}{}
   Return the context manager object itself.  This is required to
-  allow both contexts and context managers to be used with the
-  \keyword{with} statement.
+  allow both context specifiers and context managers to be used with
+  the \keyword{with} statement.
 \end{methoddesc}
 
 \begin{methoddesc}[context manager]{__enter__}{}
-  Set up the runtime context and return either the defining context
-  object or another object related to the runtime context. The value
+  Enter the runtime context and return either the defining context
+  specifier 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 with a context manager that returns the
-  original context object is file objects, which are returned from
+  original context specifier 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 manager that returns a related
-  object is \code{decimal.Context} which returns a copy of the original
-  context to allow changes to be made to the current decimal context
-  without affecting code outside the \keyword{with} statement).
+  object is \code{decimal.Context} which sets the active decimal
+  context to a copy of the context specifier and then returns the copy
+  to allow 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}[context manager]{__exit__}{exc_type, exc_val, exc_tb}
-  Tear down the runtime context and return a Boolean flag indicating if
-  an expection that occurred should be suppressed. If an exception
+  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}.
@@ -1826,20 +1829,21 @@ following three methods, which together form the
   \method{__exit__()} method has actually failed.
 \end{methoddesc}
 
-Python defines several context objects 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 protocol.
+Python defines several context specifiers 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 specification and context
+management protocols.
 
 Python's generators and the \code{contextlib.contextmanager}
 decorator provide a convenient way to implement the context
-and context management protocols.  If a context object's
-\method{__context__()} method is implemented as a generator decorated
-with the \code{contextlib.contextmanager} decorator, it will
-automatically return a context manager object supplying the
-necessary \method{__context__()}, \method{__enter__()} and
-\method{__exit__()} methods.
+specification and context management protocols.  If a context
+specifier's \method{__context__()} method is implemented as a
+generator decorated with the \code{contextlib.contextmanager}
+decorator, it will automatically return a context manager
+object supplying the necessary \method{__context__()},
+\method{__enter__()} and \method{__exit__()} methods.
 
 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

Doc/ref/ref3.tex

@@ -2112,47 +2112,45 @@ implement a \method{__coerce__()} method, for use by the built-in
 
 \end{itemize}
 
-\subsection{Context Managers and Contexts\label{context-managers}}
+\subsection{Context Specifiers and Managers\label{context-managers}}
 
 \versionadded{2.5}
 
-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.
+A \dfn{context specifier} is an object that defines the runtime
+context to be established when executing a \keyword{with}
+statement. The context specifier 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 object}
+\index{context specifier}
 
-Typical uses of contexts and context managers include saving and
+Typical uses of context specifiers and managers include saving and
 restoring various kinds of global state, locking and unlocking
 resources, closing opened files, etc.
 
-For more information on contexts and context manager objects, see
-``\ulink{Context Types}{../lib/typecontext.html}'' in the
+For more information on context specifiers 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}
+\begin{methoddesc}[context specifier]{__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 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 objects written in Python can also implement this method using
-a generator function decorated with the
+\keyword{with} statement.  The returned object must implement
+\method{__enter__()} and \method{__exit__()} methods.
+
+Context specifiers 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 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.
+required to return themselves (that is, this method will simply
+return \var{self}).
 \end{methoddesc}
 
 \begin{methoddesc}[context manager]{__enter__}{self}

Doc/ref/ref7.tex

@@ -315,10 +315,10 @@ 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 (see
+with methods defined by a context specifier or manager (see
 section~\ref{context-managers}). This allows common
 \keyword{try}...\keyword{except}...\keyword{finally} usage patterns to
-be encapsulated as context managers for convenient reuse.
+be encapsulated as context specifiers or managers for convenient reuse.
 
 \begin{productionlist}
   \production{with_stmt}
@@ -329,10 +329,10 @@ The execution of the \keyword{with} statement proceeds as follows:
 
 \begin{enumerate}
 
-\item The expression is evaluated, to obtain a context object.
+\item The expression is evaluated, to obtain a context specifier.
 
-\item The context object's \method{__context__()} method is invoked to
-obtain a context manager object.
+\item The context specifier's \method{__context__()} method is
+invoked to obtain a context manager object.
 
 \item The context manager's \method{__enter__()} method is invoked.