diff options
Diffstat (limited to 'Doc/ref/ref3.tex')
| -rw-r--r-- | Doc/ref/ref3.tex | 49 |
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 |