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

andrew.kuchling python-checkins at python.org
Tue Apr 25 14:47:26 CEST 2006

Author: andrew.kuchling Date: Tue Apr 25 14:47:25 2006 New Revision: 45711

Modified: python/trunk/Doc/whatsnew/whatsnew25.tex Log: Rework context terminology

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

--- python/trunk/Doc/whatsnew/whatsnew25.tex (original) +++ python/trunk/Doc/whatsnew/whatsnew25.tex Tue Apr 25 14:47:25 2006 @@ -667,13 +667,13 @@

\begin{itemize} \item The expression is evaluated and should result in an object -with a \method{context()} method (called a context specifier''). +with a \method{__context__()} method (called a context manager'').

\item The context specifier's \method{context()} method is called, -and must return another object (called a context manager'') that has +and must return another object (called a with-statement context object'') that has \method{enter()} and \method{exit()} methods.

-\item The context manager's \method{enter()} method is called. The value +\item The context object's \method{enter()} method is called. The value returned is assigned to \var{VAR}. If no \code{'as \var{VAR}'} clause is present, the value is simply discarded.

@@ -685,7 +685,8 @@ \function{sys.exc_info()}. The method's return value controls whether the exception is re-raised: any false value re-raises the exception, and \code{True} will result in suppressing it. You'll only rarely -want to suppress the exception; the author of the code containing the +want to suppress the exception, because if you do +the author of the code containing the '\keyword{with}' statement will never realize anything went wrong.

\item If \var{BLOCK} didn't raise an exception, @@ -724,14 +725,14 @@ method. Sometimes an object can simply return \code{self}; the \module{threading} module's lock objects do this, for example. For our database example, though, we need to create a new object; I'll -call this class \class{DatabaseContextMgr}. Our \method{context()} +call this class \class{DatabaseContext}. Our \method{context()} method must therefore look like this:

\begin{verbatim} class DatabaseConnection: ... def context (self):

@@ -742,12 +743,12 @@ "Rolls back current transaction" \end{verbatim}

-Instance of \class{DatabaseContextMgr} need the connection object so that +Instances of \class{DatabaseContext} need the connection object so that the connection object's \method{commit()} or \method{rollback()} methods can be called:

\begin{verbatim} -class DatabaseContextMgr: +class DatabaseContext: def init (self, connection): self.connection = connection \end{verbatim} @@ -759,7 +760,7 @@ the cursor to a variable name.

\begin{verbatim} -class DatabaseContextMgr: +class DatabaseContext: ... def enter (self): # Code to start a new transaction @@ -779,7 +780,7 @@ statement at the marked location.

\begin{verbatim} -class DatabaseContextMgr: +class DatabaseContext: ... def exit (self, type, value, tb): if tb is None: @@ -798,8 +799,8 @@ decorator that are useful for writing objects for use with the '\keyword{with}' statement.

-The decorator is called \function{contextmanager}, and lets you write -a simple context manager as a generator function. The generator +The decorator is called \function{contextfactory}, and lets you write +a single generator function instead of defining a new class. 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 @@ -812,9 +813,9 @@ using this decorator as:

\begin{verbatim} -from contextlib import contextmanager +from contextlib import contextfactory

- at contextmanager + at contextfactory def db_transaction (connection): cursor = connection.cursor() try: @@ -831,13 +832,12 @@ \end{verbatim}

You can also use this decorator to write the \method{context()} -method for a class without having to create a new class representing -the context manager: +method for a class:

\begin{verbatim} class DatabaseConnection:

-There's a \function{nested(\var{mgr1}, \var{mgr2}, ...)} function that -combines a number of contexts so you don't need to write -nested '\keyword{with}' statements. This example statement does two -things, starting a database transaction and acquiring a thread lock: +The \module{contextlib} module also has a \function{nested(\var{mgr1}, +\var{mgr2}, ...)} function that combines a number of contexts so you +don't need to write nested '\keyword{with}' statements. In this +example, the single '\keyword{with}' statement both starts a database +transaction and acquires a thread lock:

\begin{verbatim} lock = threading.Lock()

More information about the Python-checkins mailing list