diff options
Diffstat (limited to 'Doc/ref/ref3.tex')
| -rw-r--r-- | Doc/ref/ref3.tex | 78 |
1 files changed, 35 insertions, 43 deletions
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex index 964013f..d0c8ccf 100644 --- a/Doc/ref/ref3.tex +++ b/Doc/ref/ref3.tex @@ -1875,8 +1875,8 @@ These methods are called to implement the binary arithmetic operations (\code{+}, \code{-}, \code{*}, \code{//}, \code{\%}, \function{divmod()}\bifuncindex{divmod}, -\function{pow()}\bifuncindex{pow}, \code{**}, \code{<}\code{<}, -\code{>}\code{>}, \code{\&}, \code{\^}, \code{|}). For instance, to +\function{pow()}\bifuncindex{pow}, \code{**}, \code{<<}, +\code{>>}, \code{\&}, \code{\^}, \code{|}). For instance, to evaluate the expression \var{x}\code{+}\var{y}, where \var{x} is an instance of a class that has an \method{__add__()} method, \code{\var{x}.__add__(\var{y})} is called. The \method{__divmod__()} @@ -1915,8 +1915,8 @@ These methods are called to implement the binary arithmetic operations (\code{+}, \code{-}, \code{*}, \code{/}, \code{\%}, \function{divmod()}\bifuncindex{divmod}, -\function{pow()}\bifuncindex{pow}, \code{**}, \code{<}\code{<}, -\code{>}\code{>}, \code{\&}, \code{\^}, \code{|}) with reflected +\function{pow()}\bifuncindex{pow}, \code{**}, \code{<<}, +\code{>>}, \code{\&}, \code{\^}, \code{|}) with reflected (swapped) operands. These functions are only called if the left operand does not support the corresponding operation. For instance, to evaluate the expression \var{x}\code{-}\var{y}, where \var{y} is an @@ -1942,7 +1942,7 @@ complicated). \methodline[numeric object]{__ior__}{self, other} These methods are called to implement the augmented arithmetic operations (\code{+=}, \code{-=}, \code{*=}, \code{/=}, \code{\%=}, -\code{**=}, \code{<}\code{<=}, \code{>}\code{>=}, \code{\&=}, +\code{**=}, \code{<<=}, \code{>>=}, \code{\&=}, \code{\textasciicircum=}, \code{|=}). These methods should attempt to do the operation in-place (modifying \var{self}) and return the result (which could be, but does not have to be, \var{self}). If a specific method @@ -1983,9 +1983,9 @@ Called to implement the built-in functions \end{methoddesc} \begin{methoddesc}[numeric object]{__index__}{self} -Called to implement operator.index(). Also called whenever Python -needs an integer object (such as in slicing). Must return an integer -(int or long). +Called to implement \function{operator.index()}. Also called whenever +Python needs an integer object (such as in slicing). Must return an +integer (int or long). \versionadded{2.5} \end{methoddesc} @@ -2112,49 +2112,41 @@ implement a \method{__coerce__()} method, for use by the built-in \end{itemize} -\subsection{Context Managers and Contexts\label{context-managers}} +\subsection{With Statement Context Managers\label{context-managers}} \versionadded{2.5} -A \dfn{context manager} is an object that manages the entry to, and exit -from, a \dfn{context} surrounding a 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 manager} is an object that defines the runtime +context to be established when executing a \keyword{with} +statement. The context manager handles 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} - -Typical uses of context managers include saving and restoring various -kinds of global state, locking and unlocking resources, closing opened -files, etc. - -\begin{methoddesc}[context manager]{__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 context -managers that wish to directly -implement \method{__enter__()} and \method{__exit__()} should just -return \var{self}. - -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 -than writing individual \method{__enter__()} and \method{__exit__()} -methods when the state to be managed is complex. -\end{methoddesc} -\begin{methoddesc}[context]{__enter__}{self} -Enter the context defined 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. +Typical uses of context managers include saving and +restoring various kinds of global state, locking and unlocking +resources, closing opened files, etc. + +For more information on context managers, see +``\ulink{Context Types}{../lib/typecontextmanager.html}'' in the +\citetitle[../lib/lib.html]{Python Library Reference}. + +\begin{methoddesc}[context manager]{__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]{__exit__}{exc_type, exc_value, traceback} -Exit the context defined 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}. +\begin{methoddesc}[context manager]{__exit__} +{self, exc_type, exc_value, traceback} +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 |