[Python-checkins] r45681 - in python/trunk/Doc: lib/libcontextlib.tex lib/libstdtypes.tex ref/ref3.tex ref/ref7.tex
nick.coghlan
python-checkins at python.org
Mon Apr 24 06:17:07 CEST 2006
Author: nick.coghlan
Date: Mon Apr 24 06:17:02 2006
New Revision: 45681
Modified:
python/trunk/Doc/lib/libcontextlib.tex
python/trunk/Doc/lib/libstdtypes.tex
python/trunk/Doc/ref/ref3.tex
python/trunk/Doc/ref/ref7.tex
Log:
Change PEP 343 related documentation to use the term context specifier instead of context object
Modified: python/trunk/Doc/lib/libcontextlib.tex
==============================================================================
--- python/trunk/Doc/lib/libcontextlib.tex (original)
+++ python/trunk/Doc/lib/libcontextlib.tex Mon Apr 24 06:17:02 2006
@@ -46,12 +46,17 @@
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 @@
\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 @@
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}
Modified: python/trunk/Doc/lib/libstdtypes.tex
==============================================================================
--- python/trunk/Doc/lib/libstdtypes.tex (original)
+++ python/trunk/Doc/lib/libstdtypes.tex Mon Apr 24 06:17:02 2006
@@ -1756,20 +1756,21 @@
\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 specification protocol} consists of a single
+method that needs to be provided for a context specifier object to
+define a runtime context:
-The \dfn{context protocol} consists of a single method that needs
-to be provided for an 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 @@
\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 @@
\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
Modified: python/trunk/Doc/ref/ref3.tex
==============================================================================
--- python/trunk/Doc/ref/ref3.tex (original)
+++ python/trunk/Doc/ref/ref3.tex Mon Apr 24 06:17:02 2006
@@ -2112,47 +2112,45 @@
\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}.
+\keyword{with} statement. The returned object must implement
+\method{__enter__()} and \method{__exit__()} methods.
-Context objects written in Python can also implement this method using
-a generator function decorated with the
+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}
Modified: python/trunk/Doc/ref/ref7.tex
==============================================================================
--- python/trunk/Doc/ref/ref7.tex (original)
+++ python/trunk/Doc/ref/ref7.tex Mon Apr 24 06:17:02 2006
@@ -315,10 +315,10 @@
\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 @@
\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.
More information about the Python-checkins
mailing list