Move the PEP 343 documentation and implementation closer to the

terminology in the alpha 1 documentation.

 - "context manager" reverts to its alpha 1 definition
 - the term "context specifier" goes away entirely
 - contextlib.GeneratorContextManager is renamed GeneratorContext

There are still a number of changes relative to alpha 1:

  - the expression in the with statement is explicitly called the
    "context expression" in the language reference
  - the terms 'with statement context', 'context object' or 'with
    statement context' are used in several places instead of a bare
    'context'. The aim of this is to avoid ambiguity in relation to the
    runtime context set up when the block is executed, and the context
    objects that already exist in various application domains (such as
    decimal.Context)
  - contextlib.contextmanager is renamed to contextfactory
    This best reflects the nature of the function resulting from the
    use of that decorator
  - decimal.ContextManager is renamed to WithStatementContext
    Simple dropping the 'Manager' part wasn't possible due to the
    fact that decimal.Context already exists and means something
    different. WithStatementContext is ugly but workable.

A technically unrelated change snuck into this commit:
contextlib.closing now avoids the overhead of creating a
generator, since it's trivial to implement that particular
context manager directly.

1 files changed, 25 insertions, 24 deletions

diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index b1e1ee9..7b4089d 100644
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -2112,59 +2112,60 @@ implement a \method{__coerce__()} method, for use by the built-in
 
 \end{itemize}
 
-\subsection{Context Specifiers and Managers\label{context-managers}}
+\subsection{With Statement Contexts and Context Managers\label{context-managers}}
 
 \versionadded{2.5}
 
-A \dfn{context specifier} is an object that defines the runtime
+A \dfn{context manager} 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.
+statement. The context manager provides a
+\dfn{with statement context object} 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 specifier}
+\index{context (with statement)}
+\index{with statement context}
 
-Typical uses of context specifiers and managers include saving and
+Typical uses of context managers and contexts include saving and
 restoring various kinds of global state, locking and unlocking
 resources, closing opened files, etc.
 
-For more information on context specifiers and context manager objects,
+For more information on context managers and context objects,
 see ``\ulink{Context Types}{../lib/typecontext.html}'' in the
 \citetitle[../lib/lib.html]{Python Library Reference}.
 
-\begin{methoddesc}[context specifier]{__context__}{self}
+\begin{methoddesc}[context manager]{__context__}{self}
 Invoked when the object is used as the context expression of a
 \keyword{with} statement.  The returned object must implement
 \method{__enter__()} and \method{__exit__()} methods.
 
-Context specifiers written in Python can also implement this method
+Context managers written in Python can also implement this method
 using a generator function decorated with the
-\function{contextlib.contextmanager} decorator, as this can be simpler
+\function{contextlib.contextfactory} 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 (that is, this method will simply
+With statement context objects also need to implement this method; they
+are required to return themselves (that is, this method will simply
 return \var{self}).
 \end{methoddesc}
 
-\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.
+\begin{methoddesc}[with statement context]{__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.
 \end{methoddesc}
 
 \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}.
+Exit the runtime context related to 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}.
 
 If an exception is supplied, and the method wishes to suppress the
 exception (i.e., prevent it from being propagated), it should return a