Merge p3yk branch with the trunk up to revision 45595. This breaks a fair

number of tests, all because of the codecs/_multibytecodecs issue described
here (it's not a Py3K issue, just something Py3K discovers):
http://mail.python.org/pipermail/python-dev/2006-April/064051.html

Hye-Shik Chang promised to look for a fix, so no need to fix it here. The
tests that are expected to break are:

test_codecencodings_cn
test_codecencodings_hk
test_codecencodings_jp
test_codecencodings_kr
test_codecencodings_tw
test_codecs
test_multibytecodec

This merge fixes an actual test failure (test_weakref) in this branch,
though, so I believe merging is the right thing to do anyway.

1 files changed, 55 insertions, 17 deletions

diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex
index 054985b..7f9a7ee 100644
--- a/Doc/tut/tut.tex
+++ b/Doc/tut/tut.tex
@@ -1012,7 +1012,7 @@ individual elements of a list:
 \end{verbatim}
 
 Assignment to slices is also possible, and this can even change the size
-of the list:
+of the list or clear it entirely:
 
 \begin{verbatim}
 >>> # Replace some items:
@@ -1027,9 +1027,14 @@ of the list:
 ... a[1:1] = ['bletch', 'xyzzy']
 >>> a
 [123, 'bletch', 'xyzzy', 1234]
->>> a[:0] = a     # Insert (a copy of) itself at the beginning
+>>> # Insert (a copy of) itself at the beginning
+>>> a[:0] = a
 >>> a
 [123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234]
+>>> # Clear the list: replace all items with an empty list
+>>> a[:] = []
+>>> a
+[]
 \end{verbatim}
 
 The built-in function \function{len()} also applies to lists:
@@ -2023,9 +2028,9 @@ applied to complex expressions and nested functions:
 There is a way to remove an item from a list given its index instead
 of its value: the \keyword{del} statement.  This differs from the
 \method{pop()}) method which returns a value.  The \keyword{del}
-statement can also be used to
-remove slices from a list (which we did earlier by assignment of an
-empty list to the slice).  For example:
+statement can also be used to remove slices from a list or clear the
+entire list (which we did earlier by assignment of an empty list to
+the slice).  For example:
 
 \begin{verbatim}
 >>> a = [-1, 1, 66.25, 333, 333, 1234.5]
@@ -2035,6 +2040,9 @@ empty list to the slice).  For example:
 >>> del a[2:4]
 >>> a
 [1, 66.25, 1234.5]
+>>> del a[:]
+>>> a
+[]
 \end{verbatim}
 
 \keyword{del} can also be used to delete entire variables:
@@ -3710,19 +3718,49 @@ Traceback (most recent call last):
 KeyboardInterrupt
 \end{verbatim}
 
-A \emph{finally clause} is executed whether or not an exception has
-occurred in the try clause.  When an exception has occurred, it is
-re-raised after the finally clause is executed.  The finally clause is
-also executed ``on the way out'' when the \keyword{try} statement is
-left via a \keyword{break} or \keyword{return} statement.
+A \emph{finally clause} is always executed before leaving the
+\keyword{try} statement, whether an exception has occurred or not.
+When an exception has occurred in the \keyword{try} clause and has not
+been handled by an \keyword{except} clause (or it has occurred in a
+\keyword{except} or \keyword{else} clause), it is re-raised after the
+\keyword{finally} clause has been executed.  The \keyword{finally} clause
+is also executed ``on the way out'' when any other clause of the
+\keyword{try} statement is left via a \keyword{break}, \keyword{continue}
+or \keyword{return} statement.  A more complicated example:
+
+\begin{verbatim}
+>>> def divide(x, y):
+...     try:
+...         result = x / y
+...     except ZeroDivisionError:
+...         print "division by zero!"
+...     else:
+...         print "result is", result
+...     finally:
+...         print "executing finally clause"
+...
+>>> divide(2, 1)
+result is 2
+executing finally clause
+>>> divide(2, 0)
+division by zero!
+executing finally clause
+>>> divide("2", "1")
+executing finally clause
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+  File "<stdin>", line 3, in divide
+TypeError: unsupported operand type(s) for /: 'str' and 'str'
+\end{verbatim}
 
-The code in the finally clause is useful for releasing external
-resources (such as files or network connections), regardless of
-whether the use of the resource was successful.
+As you can see, the \keyword{finally} clause is executed in any
+event.  The \exception{TypeError} raised by dividing two strings
+is not handled by the \keyword{except} clause and therefore
+re-raised after the \keyword{finally} clauses has been executed.
 
-A \keyword{try} statement must either have one or more except clauses
-or one finally clause, but not both (because it would be unclear which
-clause should be executed first).
+In real world applications, the \keyword{finally} clause is useful
+for releasing external resources (such as files or network connections),
+regardless of whether the use of the resource was successful.
 
 
 \chapter{Classes \label{classes}}
@@ -5340,7 +5378,7 @@ users.
 
 \item \citetitle[../ref/ref.html]{Language Reference}: A detailed 
 explanation of Python's syntax and semantics.  It's heavy reading, 
-but is useful as a
+but is useful as a complete guide to the language itself.
 
 \end{itemize}