From 877cf234c903310d1b4bae41178d1921599783ee Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Mon, 24 Apr 2006 04:17:02 +0000 Subject: [PATCH] Change PEP 343 related documentation to use the term context specifier instead of context object --- Doc/lib/libcontextlib.tex | 29 +++++++++++------- Doc/lib/libstdtypes.tex | 62 +++++++++++++++++++++------------------ Doc/ref/ref3.tex | 44 +++++++++++++-------------- Doc/ref/ref7.tex | 10 +++---- 4 files changed, 78 insertions(+), 67 deletions(-) diff --git a/Doc/lib/libcontextlib.tex b/Doc/lib/libcontextlib.tex index 0c02cd1b44..2a9eb0e666 100644 --- a/Doc/lib/libcontextlib.tex +++ b/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} diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex index 0656c35e2d..ea950c8278 100644 --- a/Doc/lib/libstdtypes.tex +++ b/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 diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex index b59f937bf2..b1e1ee92cb 100644 --- a/Doc/ref/ref3.tex +++ b/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} diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex index d7929af201..0c5984721d 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 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. -- 2.40.0