mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Add two items; typographical improvement for the 'with' statement; minor edits

Browse source
This commit is contained in:
Andrew M. Kuchling 2006-04-21 13:01:45 +00:00
parent ba67a8a202
commit 42c6e2f6b2
1 changed files with 48 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

77
Doc/whatsnew/whatsnew25.tex
View file

@ -4,7 +4,6 @@
% The easy_install stuff % The easy_install stuff
% Describe the pkgutil module % Describe the pkgutil module
% Stateful codec changes
% Fix XXX comments % Fix XXX comments
% Count up the patches and bugs % Count up the patches and bugs
@ -580,7 +579,7 @@ Sugalski.}
%====================================================================== %======================================================================
\section{PEP 343: The 'with' statement} \section{PEP 343: The 'with' statement}
The \keyword{with} statement allows a clearer version of code that The '\keyword{with}' statement allows a clearer version of code that
uses \code{try...finally} blocks to ensure that clean-up code is uses \code{try...finally} blocks to ensure that clean-up code is
executed. executed.
@ -589,7 +588,7 @@ used. In the next section, I'll examine the implementation details
and show how to write objects called ``context managers'' and and show how to write objects called ``context managers'' and
``contexts'' for use with this statement. ``contexts'' for use with this statement.
The \keyword{with} statement is a new control-flow structure whose The '\keyword{with}' statement is a new control-flow structure whose
basic structure is: basic structure is:
\begin{verbatim} \begin{verbatim}
@ -625,11 +624,11 @@ with open('/etc/passwd', 'r') as f:
\end{verbatim} \end{verbatim}
After this statement has executed, the file object in \var{f} will After this statement has executed, the file object in \var{f} will
have been automatically closed at this point, even if the 'for' loop have been automatically closed, even if the 'for' loop
raised an exception part-way through the block. raised an exception part-way through the block.
The \module{threading} module's locks and condition variables The \module{threading} module's locks and condition variables
also support the \keyword{with} statement: also support the '\keyword{with}' statement:
\begin{verbatim} \begin{verbatim}
lock = threading.Lock() lock = threading.Lock()
@ -660,8 +659,8 @@ with decimal.Context(prec=16):
\subsection{Writing Context Managers} \subsection{Writing Context Managers}
Under the hood, the \keyword{with} statement is fairly complicated. Under the hood, the '\keyword{with}' statement is fairly complicated.
Most people will only use \keyword{with} in company with Most people will only use '\keyword{with}' in company with
existing objects that are documented to work as context managers, and 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 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 you like. Authors of new context managers will need to understand the
@ -678,7 +677,7 @@ that's a context manager, meaning that it has a
return a context object. return a context object.
\item The context's \method{__enter__()} method is called. \item The context's \method{__enter__()} method is called.
The value returned is assigned to \var{VAR}. If no \code{as \var{VAR}} The value returned is assigned to \var{VAR}. If no \code{'as \var{VAR}'}
clause is present, the value is simply discarded. clause is present, the value is simply discarded.
\item The code in \var{BLOCK} is executed. \item The code in \var{BLOCK} is executed.
@ -690,7 +689,7 @@ with the exception's information, the same values returned by
controls whether the exception is re-raised: any false value controls whether the exception is re-raised: any false value
re-raises the exception, and \code{True} will result in suppressing it. re-raises the exception, and \code{True} will result in suppressing it.
You'll only rarely want to suppress the exception; the You'll only rarely want to suppress the exception; the
author of the code containing the \keyword{with} statement will author of the code containing the '\keyword{with}' statement will
never realize anything went wrong. never realize anything went wrong.
\item If \var{BLOCK} didn't raise an exception, \item If \var{BLOCK} didn't raise an exception,
@ -761,7 +760,7 @@ The \method {__enter__()} method is pretty easy, having only
to start a new transaction. In this example, to start a new transaction. In this example,
the resulting cursor object would be a useful result, the resulting cursor object would be a useful result,
so the method will return it. The user can so the method will return it. The user can
then add \code{as cursor} to their \keyword{with} statement then add \code{as cursor} to their '\keyword{with}' statement
to bind the cursor to a variable name. to bind the cursor to a variable name.
\begin{verbatim} \begin{verbatim}
@ -806,7 +805,7 @@ a simple context manager as a generator. The generator should yield
exactly one value. The code up to the \keyword{yield} will be exactly one value. The code up to the \keyword{yield} will be
executed as the \method{__enter__()} method, and the value yielded executed as the \method{__enter__()} method, and the value yielded
will be the method's return value that will get bound to the variable 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 in the '\keyword{with}' statement's \keyword{as} clause, if any. The
code after the \keyword{yield} will be executed in the code after the \keyword{yield} will be executed in the
\method{__exit__()} method. Any exception raised in the block \method{__exit__()} method. Any exception raised in the block
will be raised by the \keyword{yield} statement. will be raised by the \keyword{yield} statement.
@ -854,7 +853,7 @@ class DatabaseConnection:
There's a \function{nested(\var{mgr1}, \var{mgr2}, ...)} manager that There's a \function{nested(\var{mgr1}, \var{mgr2}, ...)} manager that
combines a number of context managers so you don't need to write combines a number of context managers so you don't need to write
nested \keyword{with} statements. This example statement does two nested '\keyword{with}' statements. This example statement does two
things, starting a database transaction and acquiring a thread lock: things, starting a database transaction and acquiring a thread lock:
\begin{verbatim} \begin{verbatim}
@ -880,7 +879,7 @@ with closing(urllib.urlopen('http://www.yahoo.com')) as f:
\seepep{343}{The ``with'' statement}{PEP written by Guido van~Rossum \seepep{343}{The ``with'' statement}{PEP written by Guido van~Rossum
and Nick Coghlan; implemented by Mike Bland, Guido van~Rossum, and and Nick Coghlan; implemented by Mike Bland, Guido van~Rossum, and
Neal Norwitz. The PEP shows the code generated for a \keyword{with} Neal Norwitz. The PEP shows the code generated for a '\keyword{with}'
statement, which can be helpful in learning how context managers statement, which can be helpful in learning how context managers
work.} work.}
@ -1092,8 +1091,8 @@ print d[3], d[4] # Prints 0, 0
\end{verbatim} \end{verbatim}
\item The \function{min()} and \function{max()} built-in functions \item The \function{min()} and \function{max()} built-in functions
gained a \code{key} keyword argument analogous to the \code{key} gained a \code{key} keyword parameter analogous to the \code{key}
argument for \method{sort()}. This argument supplies a function that argument for \method{sort()}. This parameter supplies a function that
takes a single argument and is called for every value in the list; takes a single argument and is called for every value in the list;
\function{min()}/\function{max()} will return the element with the \function{min()}/\function{max()} will return the element with the
smallest/largest return value from this function. smallest/largest return value from this function.
@ -1186,7 +1185,7 @@ pystone benchmark around XXX\% faster than Python 2.4.
%====================================================================== %======================================================================
\section{New, Improved, and Deprecated Modules} \section{New, Improved, and Removed Modules}
The standard library received many enhancements and bug fixes in The standard library received many enhancements and bug fixes in
Python 2.5. Here's a partial list of the most notable changes, sorted Python 2.5. Here's a partial list of the most notable changes, sorted
@ -1196,13 +1195,23 @@ the SVN logs for all the details.
\begin{itemize} \begin{itemize}
% the cPickle module no longer accepts the deprecated None option in the
% args tuple returned by __reduce__().
\item The \module{audioop} module now supports the a-LAW encoding, \item The \module{audioop} module now supports the a-LAW encoding,
and the code for u-LAW encoding has been improved. (Contributed by and the code for u-LAW encoding has been improved. (Contributed by
Lars Immisch.) Lars Immisch.)
\item The \module{codecs} module gained support for incremental
codecs. The \function{codec.lookup()} function now
returns a \class{CodecInfo} instance instead of a tuple.
\class{CodecInfo} instances behave like a 4-tuple to preserve backward
compatibility but also have the attributes \member{encode},
\member{decode}, \member{incrementalencoder}, \member{incrementaldecoder},
\member{streamwriter}, and \member{streamreader}. Incremental codecs
can receive input and produce output in multiple chunks; the output is
the same as if the entire input was fed to the non-incremental codec.
See the \module{codecs} module documentation for details.
(Designed and implemented by Walter D\"orwald.)
% Patch 1436130
\item The \module{collections} module gained a new type, \item The \module{collections} module gained a new type,
\class{defaultdict}, that subclasses the standard \class{dict} \class{defaultdict}, that subclasses the standard \class{dict}
type. The new type mostly behaves like a dictionary but constructs a type. The new type mostly behaves like a dictionary but constructs a
@ -1244,7 +1253,7 @@ method that removes the first occurrence of \var{value} in the queue,
raising \exception{ValueError} if the value isn't found. raising \exception{ValueError} if the value isn't found.
\item New module: The \module{contextlib} module contains helper functions for use \item New module: The \module{contextlib} module contains helper functions for use
with the new \keyword{with} statement. See with the new '\keyword{with}' statement. See
section~\ref{module-contextlib} for more about this module. section~\ref{module-contextlib} for more about this module.
(Contributed by Phillip J. Eby.) (Contributed by Phillip J. Eby.)
@ -1302,7 +1311,7 @@ to specify which generation to collect.
\item The \function{nsmallest()} and \item The \function{nsmallest()} and
\function{nlargest()} functions in the \module{heapq} module \function{nlargest()} functions in the \module{heapq} module
now support a \code{key} keyword argument similar to the one now support a \code{key} keyword parameter similar to the one
provided by the \function{min()}/\function{max()} functions provided by the \function{min()}/\function{max()} functions
and the \method{sort()} methods. For example: and the \method{sort()} methods. For example:
Example: Example:
@ -1375,14 +1384,20 @@ The \member{st_flags} member is also available, if the platform supports it.
(Contributed by Antti Louko and Diego Petten\`o.) (Contributed by Antti Louko and Diego Petten\`o.)
% (Patch 1180695, 1212117) % (Patch 1180695, 1212117)
\item The \module{pickle} and \module{cPickle} modules no
longer accept a return value of \code{None} from the
\method{__reduce__()} method; the method must return a tuple of
arguments instead. The ability to return \code{None} was deprecated
in Python 2.4, so this completes the removal of the feature.
\item The old \module{regex} and \module{regsub} modules, which have been \item The old \module{regex} and \module{regsub} modules, which have been
deprecated ever since Python 2.0, have finally been deleted. deprecated ever since Python 2.0, have finally been deleted.
Other deleted modules: \module{statcache}, \module{tzparse}, Other deleted modules: \module{statcache}, \module{tzparse},
\module{whrandom}. \module{whrandom}.
\item The \file{lib-old} directory, \item Also deleted: the \file{lib-old} directory,
which includes ancient modules such as \module{dircmp} and which includes ancient modules such as \module{dircmp} and
\module{ni}, was also deleted. \file{lib-old} wasn't on the default \module{ni}, was removed. \file{lib-old} wasn't on the default
\code{sys.path}, so unless your programs explicitly added the directory to \code{sys.path}, so unless your programs explicitly added the directory to
\code{sys.path}, this removal shouldn't affect your code. \code{sys.path}, this removal shouldn't affect your code.
@ -1969,18 +1984,22 @@ a syntax error if a module contains string literals with 8-bit
characters but doesn't have an encoding declaration. In Python 2.4 characters but doesn't have an encoding declaration. In Python 2.4
this triggered a warning, not a syntax error. this triggered a warning, not a syntax error.
\item The \module{pickle} module no longer uses the deprecated \var{bin} parameter.
\item Previously, the \member{gi_frame} attribute of a generator \item Previously, the \member{gi_frame} attribute of a generator
was always a frame object. Because of the \pep{342} changes was always a frame object. Because of the \pep{342} changes
described in section~\ref{section-generators}, it's now possible described in section~\ref{section-generators}, it's now possible
for \member{gi_frame} to be \code{None}. for \member{gi_frame} to be \code{None}.
\item Library: The \module{pickle} and \module{cPickle} modules no
longer accept a return value of \code{None} from the
\method{__reduce__()} method; the method must return a tuple of
arguments instead. The modules also no longer accept the deprecated
\var{bin} keyword parameter.
\item C API: Many functions now use \ctype{Py_ssize_t} \item C API: Many functions now use \ctype{Py_ssize_t}
instead of \ctype{int} to allow processing more data instead of \ctype{int} to allow processing more data on 64-bit
on 64-bit machines. Extension code may need to make machines. Extension code may need to make the same change to avoid
the same change to avoid warnings and to support 64-bit machines. warnings and to support 64-bit machines. See the earlier
See the earlier
section~\ref{section-353} for a discussion of this change. section~\ref{section-353} for a discussion of this change.
\item C API: \item C API: