[Python-checkins] r45457 - python/trunk/Doc/whatsnew/whatsnew25.tex (original) (raw)

andrew.kuchling python-checkins at python.org
Sun Apr 16 20:45:12 CEST 2006

Author: andrew.kuchling Date: Sun Apr 16 20:45:11 2006 New Revision: 45457

Modified: python/trunk/Doc/whatsnew/whatsnew25.tex Log: Describe contextlib module. (Done for today...)

Modified: python/trunk/Doc/whatsnew/whatsnew25.tex

--- python/trunk/Doc/whatsnew/whatsnew25.tex (original) +++ python/trunk/Doc/whatsnew/whatsnew25.tex Sun Apr 16 20:45:11 2006 @@ -585,11 +585,7 @@ First, I'll discuss the statement as it will commonly be used, and then a subsection will examine the implementation details and how to write objects (called ``context managers'') that can be used with this -statement. Most people will only use \keyword{with} in company with -existing objects that are documented to work as context managers, and -don't need to know these details, so you can skip the subsection if -you like. Authors of new context managers will need to understand the -details of the underlying implementation. +statement.

The \keyword{with} statement is a new control-flow structure whose basic structure is: @@ -663,7 +659,11 @@ \subsection{Writing Context Managers}

Under the hood, the \keyword{with} statement is fairly complicated. -The interface demanded of context managers contains several methods. +Most people will only use \keyword{with} in company with +existing objects that are documented to work as context managers, and +don't need to know these details, so you can skip the following section if +you like. Authors of new context managers will need to understand the +details of the underlying implementation.

A high-level explanation of the context management protocol is:

@@ -826,19 +826,74 @@ \end{verbatim} \end{comment}

+\subsection{The contextlib module\label{module-contextlib}}

The new \module{contextlib} module provides some functions and a -decorator that are useful for writing context managers.
-Future versions will go into more detail. +decorator that are useful for writing context managers. + +The decorator is called \function{contextmanager}, and lets you write +a simple context manager as a generator. The generator should yield +exactly one value. The code up to the \keyword{yield} will be +executed as the \method{enter()} method, and the value yielded +will be the method's return value that will get bound to the variable +in the \keyword{with} statement's \keyword{as} clause, if any. The +code after the \keyword{yield} will be executed in the +\method{exit()} method. Any exception raised in the block +will be raised by the \keyword{yield} statement. + +Our database example from the previous section could be written +using this decorator as: + +\begin{verbatim} +from contextlib import contextmanager + + at contextmanager +def db_transaction (connection):

+\end{verbatim}

-% XXX describe further +There's a \function{nested(\var{mgr1}, \var{mgr2}, ...)} manager that +combines a number of context managers so you don't need to write +nested \keyword{with} statements. This example +both uses a database transaction and also acquires a thread lock: + +\begin{verbatim} +lock = threading.Lock() +with nested (db_transaction(db), lock) as (cursor, locked):

+\end{verbatim} + +Finally, the \function{closing(\var{object})} context manager +returns \var{object} so that it can be bound to a variable, +and calls \code{\var{object}.close()} at the end of the block. + +\begin{verbatim} +with closing(open('/tmp/file', 'r')) as f:

+\end{verbatim}

\begin{seealso}

-\seepep{343}{The with'' statement}{PEP written by -Guido van Rossum and Nick Coghlan. -The PEP shows the code generated for a \keyword{with} statement, -which can be helpful in learning how context managers work.} +\seepep{343}{The with'' statement}{PEP written by Guido van Rossum +and Nick Coghlan; implemented by Mike Bland, Guido van Rossum, and +Neal Norwitz. The PEP shows the code generated for a \keyword{with} +statement, which can be helpful in learning how context managers +work.} + +\seeurl{../lib/module-contextlib.html}{The documentation +for the \module{contextlib} module.}

\end{seealso}

@@ -1140,12 +1195,11 @@ %====================================================================== \section{New, Improved, and Deprecated Modules}

-As usual, Python's standard library received many enhancements and -bug fixes. Here's a partial list of the most notable changes, sorted -alphabetically by module name. Consult the -\file{Misc/NEWS} file in the source tree for a more -complete list of changes, or look through the SVN logs for all the -details. +The standard library received many enhancements and bug fixes in +Python 2.5. Here's a partial list of the most notable changes, sorted +alphabetically by module name. Consult the \file{Misc/NEWS} file in +the source tree for a more complete list of changes, or look through +the SVN logs for all the details.

\begin{itemize}

@@ -1206,6 +1260,10 @@ method that removes the first occurrence of \var{value} in the queue, raising \exception{ValueError} if the value isn't found.

+\item The \module{contextlib} module contains helper functions for use +with the new \keyword{with} statement. See section~\ref{module-contextlib} +for more about this module. (Contributed by Phillip J. Eby.) + \item The \module{cProfile} module is a C implementation of the existing \module{profile} module that has much lower overhead. The module's interface is the same as \module{profile}: you run

More information about the Python-checkins mailing list