diff options
author | Nick Coghlan <ncoghlan@gmail.com> | 2006-04-25 10:56:51 (GMT) |
---|---|---|
committer | Nick Coghlan <ncoghlan@gmail.com> | 2006-04-25 10:56:51 (GMT) |
commit | a7e820a408fa3df02f8d42a183e06774e05cd871 (patch) | |
tree | e6b219df2083f695df8917045c785dc6acac6584 /Doc/lib/libstdtypes.tex | |
parent | 327ea38cc4dc4b7dde621f78e57401fd97ef48cc (diff) | |
download | cpython-a7e820a408fa3df02f8d42a183e06774e05cd871.zip cpython-a7e820a408fa3df02f8d42a183e06774e05cd871.tar.gz cpython-a7e820a408fa3df02f8d42a183e06774e05cd871.tar.bz2 |
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.
Diffstat (limited to 'Doc/lib/libstdtypes.tex')
-rw-r--r-- | Doc/lib/libstdtypes.tex | 83 |
1 files changed, 41 insertions, 42 deletions
diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex index ea950c8..50be0fa 100644 --- a/Doc/lib/libstdtypes.tex +++ b/Doc/lib/libstdtypes.tex @@ -1756,59 +1756,59 @@ implemented in C will have to provide a writable \subsection{Context Types \label{typecontext}} \versionadded{2.5} -\index{context specification protocol} +\index{with statement context protocol} \index{context management protocol} -\index{protocol!context specification} +\index{protocol!with statement context} \index{protocol!context management} Python's \keyword{with} statement supports the concept of a runtime -context defined by a context specifier. This is implemented using +context defined by a context manager. This is implemented using three distinct methods; these are used to allow user-defined -classes to define a context. +classes 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 +The \dfn{context management protocol} consists of a single +method that needs to be provided for a context manager object to define a runtime 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 - be provided to specifically request context managers for those - kinds of context. (An example of an object supporting multiple kinds - of context would be a synchronisation object which supported both - a locked context for normal thread synchronisation and an unlocked - context to temporarily release a held lock while performing a - potentially long running operation) +\begin{methoddesc}[context manager]{__context__}{} + Return a with statement context object. The object is required to + support the with statement context protocol described below. If an + object supports different kinds of runtime context, additional + methods can be provided to specifically request context objects for + those kinds of runtime context. (An example of an object supporting + multiple kinds of context would be a synchronisation object which + supported both a locked context for normal thread synchronisation + and an unlocked context to temporarily release a held lock while + performing a potentially long running operation) \end{methoddesc} -The context manager objects themselves are required to support the +The with statement context objects themselves are required to support the following three methods, which together form the -\dfn{context management protocol}: +\dfn{with statement context protocol}: -\begin{methoddesc}[context manager]{__context__}{} - Return the context manager object itself. This is required to - allow both context specifiers and context managers to be used with - the \keyword{with} statement. +\begin{methoddesc}[with statement context]{__context__}{} + Return the context object itself. This is required to allow both + context objects and context managers to be used in a \keyword{with} + statement. \end{methoddesc} -\begin{methoddesc}[context manager]{__enter__}{} +\begin{methoddesc}[with statement context]{__enter__}{} Enter the runtime context and return either the defining context - specifier or another object related to the runtime context. The value + manager 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 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 + (An example of a context object that returns the original context + manager 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 object that returns a related 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 + context to a copy of the context manager and then returns the copy. + This allows 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} +\begin{methoddesc}[with statement context]{__exit__}{exc_type, exc_val, exc_tb} 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 @@ -1829,19 +1829,18 @@ following three methods, which together form the \method{__exit__()} method has actually failed. \end{methoddesc} -Python defines several context specifiers and managers to support +Python defines several context objects 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 -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 +implementation of the context management and with statement context +protocols. + +Python's generators and the \code{contextlib.contextfactory} decorator +provide a convenient way to implement these protocols. If a context +manager's \method{__context__()} method is implemented as a +generator decorated with the \code{contextlib.contextfactory} +decorator, it will automatically return a with statement context object supplying the necessary \method{__context__()}, \method{__enter__()} and \method{__exit__()} methods. |