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, 8 insertions, 8 deletions

diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex
index 0c5984721d..180e22fde4 100644
--- a/Doc/ref/ref7.tex
+++ b/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 specifier or manager (see
-section~\ref{context-managers}). This allows common
+with methods defined by a context manager or with statement context
+object (see section~\ref{context-managers}). This allows common
 \keyword{try}...\keyword{except}...\keyword{finally} usage patterns to
-be encapsulated as context specifiers or managers for convenient reuse.
+be encapsulated for convenient reuse.
 
 \begin{productionlist}
   \production{with_stmt}
@@ -329,12 +329,12 @@ The execution of the \keyword{with} statement proceeds as follows:
 
 \begin{enumerate}
 
-\item The expression is evaluated, to obtain a context specifier.
+\item The context expression is evaluated, to obtain a context manager.
 
-\item The context specifier's \method{__context__()} method is
-invoked to obtain a context manager object.
+\item The context manger's \method{__context__()} method is
+invoked to obtain a with statement context object.
 
-\item The context manager's \method{__enter__()} method is invoked.
+\item The context object'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.
@@ -347,7 +347,7 @@ an error occurring within the suite would be. See step 6 below.}
 
 \item The suite is executed.
 
-\item The context manager's \method{__exit__()} method is invoked. If
+\item The context object'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.