Merge in changes from the 1.5.2p2 release.

1 files changed, 410 insertions, 267 deletions

diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex
index cb7a4d1..ead1be4 100644
--- a/Doc/tut/tut.tex
+++ b/Doc/tut/tut.tex
@@ -3,7 +3,7 @@
 % Things to do:
 % Add a section on file I/O
 % Write a chapter entitled ``Some Useful Modules''
-%  --regex, math+cmath
+%  --re, math+cmath
 % Should really move the Python startup file info to an appendix
 
 \title{Python Tutorial}
@@ -114,8 +114,8 @@ programs, or to test functions during bottom-up program development.
 It is also a handy desk calculator.
 
 Python allows writing very compact and readable programs.  Programs
-written in Python are typically much shorter than equivalent C
-programs, for several reasons:
+written in Python are typically much shorter than equivalent C or
+\Cpp{} programs, for several reasons:
 \begin{itemize}
 \item
 the high-level data types allow you to express complex operations in a
@@ -160,10 +160,10 @@ and user-defined classes.
 
 \section{Invoking the Interpreter \label{invoking}}
 
-The Python interpreter is usually installed as \file{/usr/local/bin/python}
-on those machines where it is available; putting \file{/usr/local/bin} in
-your \UNIX{} shell's search path makes it possible to start it by
-typing the command
+The Python interpreter is usually installed as
+\file{/usr/local/bin/python} on those machines where it is available;
+putting \file{/usr/local/bin} in your \UNIX{} shell's search path
+makes it possible to start it by typing the command
 
 \begin{verbatim}
 python
@@ -237,10 +237,8 @@ not consumed by the Python interpreter's option processing but left in
 When commands are read from a tty, the interpreter is said to be in
 \emph{interactive mode}.  In this mode it prompts for the next command
 with the \emph{primary prompt}, usually three greater-than signs
-(\samp{>>> }); for continuation lines it prompts with the
-\emph{secondary prompt},
-by default three dots (\samp{... }).  
-
+(\samp{>>>~}); for continuation lines it prompts with the
+\emph{secondary prompt}, by default three dots (\samp{...~}).
 The interpreter prints a welcome message stating its version number
 and a copyright notice before printing the first prompt, e.g.:
 
@@ -251,6 +249,18 @@ Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
 >>>
 \end{verbatim}
 
+Continuation lines are needed when entering a multi-line construct.
+As an example, take a look at this \keyword{if} statement:
+
+\begin{verbatim}
+>>> the_world_is_flat = 1
+>>> if the_world_is_flat:
+...     print "Be careful not to fall off!"
+... 
+Be careful not to fall off!
+\end{verbatim}
+
+
 \section{The Interpreter and Its Environment \label{interp}}
 
 \subsection{Error Handling \label{error}}
@@ -300,8 +310,8 @@ When you use Python interactively, it is frequently handy to have some
 standard commands executed every time the interpreter is started.  You
 can do this by setting an environment variable named
 \envvar{PYTHONSTARTUP} to the name of a file containing your start-up
-commands.  This is similar to the \file{.profile} feature of the \UNIX{}
-shells.
+commands.  This is similar to the \file{.profile} feature of the
+\UNIX{} shells.
 
 This file is only read in interactive sessions, not when Python reads
 commands from a script, and not when \file{/dev/tty} is given as the
@@ -329,7 +339,7 @@ if os.environ.get('PYTHONSTARTUP') \
 \chapter{An Informal Introduction to Python \label{informal}}
 
 In the following examples, input and output are distinguished by the
-presence or absence of prompts (\samp{>>> } and \samp{... }): to repeat
+presence or absence of prompts (\samp{>>>~} and \samp{...~}): to repeat
 the example, you must type everything after the prompt, when the
 prompt appears; lines that do not begin with a prompt are output from
 the interpreter. %
@@ -367,9 +377,9 @@ for the primary prompt, \samp{>>> }.  (It shouldn't take long.)
 
 The interpreter acts as a simple calculator: you can type an
 expression at it and it will write the value.  Expression syntax is
-straightforward: the operators \code{+}, \code{-}, \code{*} and \code{/}
-work just like in most other languages (e.g., Pascal or C); parentheses
-can be used for grouping.  For example:
+straightforward: the operators \code{+}, \code{-}, \code{*} and
+\code{/} work just like in most other languages (for example, Pascal
+or C); parentheses can be used for grouping.  For example:
 
 \begin{verbatim}
 >>> 2+2
@@ -397,7 +407,7 @@ variable.  The value of an assignment is not written:
 >>> width * height
 900
 \end{verbatim}
-%
+
 A value can be assigned to several variables simultaneously:
 
 \begin{verbatim}
@@ -557,8 +567,8 @@ a single quote and no double quotes, else it's enclosed in single
 quotes.  (The \keyword{print} statement, described later, can be used
 to write strings without quotes or escapes.)
 
-Strings can be concatenated (glued together) with the \code{+}
-operator, and repeated with \code{*}:
+Strings can be concatenated (glued together) with the
+\code{+} operator, and repeated with \code{*}:
 
 \begin{verbatim}
 >>> word = 'Help' + 'A'
@@ -601,6 +611,30 @@ separated by a colon.
 'lp'
 \end{verbatim}
 
+Unlike a C string, Python strings cannot be changed.  Assigning to an 
+indexed position in the string results in an error:
+
+\begin{verbatim}
+>>> word[0] = 'x'
+Traceback (innermost last):
+  File "<stdin>", line 1, in ?
+TypeError: object doesn't support item assignment
+>>> word[:-1] = 'Splat'
+Traceback (innermost last):
+  File "<stdin>", line 1, in ?
+TypeError: object doesn't support slice assignment
+\end{verbatim}
+
+However, creating a new string with the combined content is easy and
+efficient:
+
+\begin{verbatim}
+>>> 'x' + word[1:]
+'xelpA'
+>>> 'Splat' + word[-1:]
+'SplatA'
+\end{verbatim}
+
 Slice indices have useful defaults; an omitted first index defaults to
 zero, an omitted second index defaults to the size of the string being
 sliced.
@@ -612,8 +646,8 @@ sliced.
 'lpA'
 \end{verbatim}
 
-Here's a useful invariant of slice operations: \code{s[:i] + s[i:]}
-equals \code{s}.
+Here's a useful invariant of slice operations:
+\code{s[:i] + s[i:]} equals \code{s}.
 
 \begin{verbatim}
 >>> word[:2] + word[2:]
@@ -687,7 +721,7 @@ the string; the second row gives the corresponding negative indices.
 The slice from \var{i} to \var{j} consists of all characters between
 the edges labeled \var{i} and \var{j}, respectively.
 
-For nonnegative indices, the length of a slice is the difference of
+For non-negative indices, the length of a slice is the difference of
 the indices, if both are within bounds, e.g., the length of
 \code{word[1:3]} is 2.
 
@@ -822,7 +856,8 @@ The first line contains a \emph{multiple assignment}: the variables
 \code{a} and \code{b} simultaneously get the new values 0 and 1.  On the
 last line this is used again, demonstrating that the expressions on
 the right-hand side are all evaluated first before any of the
-assignments take place.
+assignments take place.  The right-hand side expressions are evaluated 
+from the left to the right.
 
 \item
 The \keyword{while} loop executes as long as the condition (here:
@@ -831,8 +866,9 @@ integer value is true; zero is false.  The condition may also be a
 string or list value, in fact any sequence; anything with a non-zero
 length is true, empty sequences are false.  The test used in the
 example is a simple comparison.  The standard comparison operators are
-written the same as in C: \code{<}, \code{>}, \code{==}, \code{<=},
-\code{>=} and \code{!=}.
+written the same as in C: \code{<} (less than), \code{>} (greater than),
+\code{==} (equal to), \code{<=} (less than or equal to),
+\code{>=} (greater than or equal to) and \code{!=} (not equal to).
 
 \item
 The \emph{body} of the loop is \emph{indented}: indentation is Python's
@@ -843,7 +879,8 @@ complicated input for Python with a text editor; most text editors have
 an auto-indent facility.  When a compound statement is entered
 interactively, it must be followed by a blank line to indicate
 completion (since the parser cannot guess when you have typed the last
-line).
+line).  Note that each line within a basic block must be indented by
+the same amount.
 
 \item
 The \keyword{print} statement writes the value of the expression(s) it is
@@ -884,11 +921,11 @@ some twists.
 
 \section{\keyword{if} Statements \label{if}}
 
-Perhaps the most well-known statement type is the \keyword{if}
-statement.  For example:
+Perhaps the most well-known statement type is the
+\keyword{if} statement.  For example:
 
 \begin{verbatim}
->>> #  [Code which sets 'x' to a value...]
+>>> x = int(raw_input("Please enter a number: "))
 >>> if x < 0:
 ...      x = 0
 ...      print 'Negative changed to zero'
@@ -901,14 +938,13 @@ statement.  For example:
 ... 
 \end{verbatim}
 
-There can be zero or more \keyword{elif} parts, and the \keyword{else}
-part is optional.  The keyword `\keyword{elif}' is short for `else
-if', and is useful to avoid excessive indentation.  An
-\keyword{if} \ldots\ \keyword{elif} \ldots\ \keyword{elif}
-\ldots\ sequence is a substitute for the  \emph{switch} or
-%    ^^^^
+There can be zero or more \keyword{elif} parts, and the
+\keyword{else} part is optional.  The keyword `\keyword{elif}' is
+short for `else if', and is useful to avoid excessive indentation.  An 
+\keyword{if} \ldots\ \keyword{elif} \ldots\ \keyword{elif} \ldots\ sequence
 %    Weird spacings happen here if the wrapping of the source text
 %    gets changed in the wrong way.
+is a substitute for the  \emph{switch} or
 \emph{case} statements found in other languages.
 
 
@@ -918,10 +954,10 @@ The \keyword{for}\stindex{for} statement in Python differs a bit from
 what you may be used to in C or Pascal.  Rather than always
 iterating over an arithmetic progression of numbers (like in Pascal),
 or giving the user the ability to define both the iteration step and
-halting condition (as C), Python's \keyword{for}\stindex{for}
-statement iterates over the items of any sequence (e.g., a list or a
-string), in the order that they appear in the sequence.  For example
-(no pun intended):
+halting condition (as C), Python's
+\keyword{for}\stindex{for} statement iterates over the items of any
+sequence (e.g., a list or a string), in the order that they appear in
+the sequence.  For example (no pun intended):
 % One suggestion was to give a real C example here, but that may only
 % serve to confuse non-C programmers.
 
@@ -966,7 +1002,7 @@ The given end point is never part of the generated list;
 \code{range(10)} generates a list of 10 values, exactly the legal
 indices for items of a sequence of length 10.  It is possible to let
 the range start at another number, or to specify a different increment
-(even negative):
+(even negative; sometimes this is called the `step'):
 
 \begin{verbatim}
 >>> range(5, 10)
@@ -977,8 +1013,8 @@ the range start at another number, or to specify a different increment
 [-10, -40, -70]
 \end{verbatim}
 
-To iterate over the indices of a sequence, combine \function{range()}
-and \function{len()} as follows:
+To iterate over the indices of a sequence, combine
+\function{range()} and \function{len()} as follows:
 
 \begin{verbatim}
 >>> a = ['Mary', 'had', 'a', 'little', 'lamb']
@@ -992,6 +1028,7 @@ and \function{len()} as follows:
 4 lamb
 \end{verbatim}
 
+
 \section{\keyword{break} and \keyword{continue} Statements, and
          \keyword{else} Clauses on Loops
          \label{break}}
@@ -1062,13 +1099,15 @@ arbitrary boundary:
 The keyword \keyword{def} introduces a function \emph{definition}.  It
 must be followed by the function name and the parenthesized list of
 formal parameters.  The statements that form the body of the function
-start at the next line, indented by a tab stop.  The first statement
-of the function body can optionally be a string literal; this string
-literal is the function's documentation string, or \dfn{docstring}.
-There are tools which use docstrings to automatically produce printed
-documentation, or to let the user interactively browse through code;
-it's good practice to include docstrings in code that you write, so
-try to make a habit of it.
+start at the next line, and must be indented.  The first statement of
+the function body can optionally be a string literal; this string
+literal is the function's \index{documentation strings}documentation
+string, or \dfn{docstring}.\index{docstrings}\index{strings, documentation}
+
+There are tools which use docstrings to automatically produce online
+or printed documentation, or to let the user interactively browse
+through code; it's good practice to include docstrings in code that
+you write, so try to make a habit of it.
 
 The \emph{execution} of a function introduces a new symbol table used
 for the local variables of the function.  More precisely, all variable
@@ -1081,13 +1120,14 @@ they may be referenced.
 
 The actual parameters (arguments) to a function call are introduced in
 the local symbol table of the called function when it is called; thus,
-arguments are passed using \emph{call by value}.\footnote{
+arguments are passed using \emph{call by value} (where the
+\emph{value} is always an object \emph{reference}, not the value of
+the object).\footnote{
          Actually, \emph{call by object reference} would be a better
          description, since if a mutable object is passed, the caller
          will see any changes the callee makes to it (e.g., items
          inserted into a list).
-}
-When a function calls another function, a new local symbol table is
+} When a function calls another function, a new local symbol table is
 created for that call.
 
 A function definition introduces the function name in the current
@@ -1287,11 +1327,11 @@ TypeError: keyword parameter redefined
 When a final formal parameter of the form \code{**\var{name}} is
 present, it receives a dictionary containing all keyword arguments
 whose keyword doesn't correspond to a formal parameter.  This may be
-combined with a formal parameter of the form \code{*\var{name}}
-(described in the next subsection) which receives a tuple containing
-the positional arguments beyond the formal parameter list.
-(\code{*\var{name}} must occur before \code{**\var{name}}.)  For
-example, if we define a function like this:
+combined with a formal parameter of the form
+\code{*\var{name}} (described in the next subsection) which receives a
+tuple containing the positional arguments beyond the formal parameter
+list.  (\code{*\var{name}} must occur before \code{**\var{name}}.)
+For example, if we define a function like this:
 
 \begin{verbatim}
 def cheeseshop(kind, *arguments, **keywords):
@@ -1356,10 +1396,13 @@ def make_incrementor(n):
     return lambda x, incr=n: x+incr
 \end{verbatim}
 
+
 \subsection{Documentation Strings \label{docstrings}}
 
 There are emerging conventions about the content and formatting of
 documentation strings.
+\index{docstrings}\index{documentation strings}
+\index{strings, documentation}
 
 The first line should always be a short, concise summary of the
 object's purpose.  For brevity, it should not explicitly state the
@@ -1375,16 +1418,33 @@ describing the object's calling conventions, its side effects, etc.
 
 The Python parser does not strip indentation from multi-line string
 literals in Python, so tools that process documentation have to strip
-indentation.  This is done using the following convention.  The first
-non-blank line \emph{after} the first line of the string determines the
-amount of indentation for the entire documentation string.  (We can't
-use the first line since it is generally adjacent to the string's
-opening quotes so its indentation is not apparent in the string
-literal.)  Whitespace ``equivalent'' to this indentation is then
-stripped from the start of all lines of the string.  Lines that are
-indented less should not occur, but if they occur all their leading
-whitespace should be stripped.  Equivalence of whitespace should be
-tested after expansion of tabs (to 8 spaces, normally).
+indentation if desired.  This is done using the following convention.
+The first non-blank line \emph{after} the first line of the string
+determines the amount of indentation for the entire documentation
+string.  (We can't use the first line since it is generally adjacent
+to the string's opening quotes so its indentation is not apparent in
+the string literal.)  Whitespace ``equivalent'' to this indentation is
+then stripped from the start of all lines of the string.  Lines that
+are indented less should not occur, but if they occur all their
+leading whitespace should be stripped.  Equivalence of whitespace
+should be tested after expansion of tabs (to 8 spaces, normally).
+
+Here is an example of a multi-line docstring:
+
+\begin{verbatim}
+>>> def my_function():
+...     """Do nothing, but document it.
+... 
+...     No, really, it doesn't do anything.
+...     """
+...     pass
+... 
+>>> print my_function.__doc__
+Do nothing, but document it.
+
+    No, really, it doesn't do anything.
+    
+\end{verbatim}
 
 
 
@@ -1393,6 +1453,7 @@ tested after expansion of tabs (to 8 spaces, normally).
 This chapter describes some things you've learned about already in
 more detail, and adds some new things as well.
 
+
 \section{More on Lists \label{moreLists}}
 
 The list data type has some more methods.  Here are all of the methods
@@ -1400,23 +1461,35 @@ of list objects:
 
 \begin{description}
 
+\item[\code{append(x)}]
+Add an item to the end of the list;
+equivalent to \code{a[len(a):] = [x]}.
+
+\item[\code{extend(L)}]
+Extend the list by appending all the items in the given list;
+equivalent to \code{a[len(a):] = L}.
+
 \item[\code{insert(i, x)}]
 Insert an item at a given position.  The first argument is the index of
 the element before which to insert, so \code{a.insert(0, x)} inserts at
 the front of the list, and \code{a.insert(len(a), x)} is equivalent to
 \code{a.append(x)}.
 
-\item[\code{append(x)}]
-Append an item to the list;
-equivalent to \code{a.insert(len(a), x)}.
+\item[\code{remove(x)}]
+Remove the first item from the list whose value is \code{x}.
+It is an error if there is no such item.
+
+\item[\code{pop(\optional{i})}]
+Remove the item at the given position in the list, and return it.  If
+no index is specified, \code{a.pop()} returns the last item in the
+list.  The item is also removed from the list.
 
 \item[\code{index(x)}]
 Return the index in the list of the first item whose value is \code{x}.
 It is an error if there is no such item.
 
-\item[\code{remove(x)}]
-Remove the first item from the list whose value is \code{x}.
-It is an error if there is no such item.
+\item[\code{count(x)}]
+Return the number of times \code{x} appears in the list.
 
 \item[\code{sort()}]
 Sort the items of the list, in place.
@@ -1424,12 +1497,9 @@ Sort the items of the list, in place.
 \item[\code{reverse()}]
 Reverse the elements of the list, in place.
 
-\item[\code{count(x)}]
-Return the number of times \code{x} appears in the list.
-
 \end{description}
 
-An example that uses all list methods:
+An example that uses most of the list methods:
 
 \begin{verbatim}
 >>> a = [66.6, 333, 333, 1, 1234.5]
@@ -1452,6 +1522,57 @@ An example that uses all list methods:
 [-1, 1, 66.6, 333, 333, 1234.5]
 \end{verbatim}
 
+
+\subsection{Using Lists as Stacks \label{lists-as-stacks}}
+\sectionauthor{Ka-Ping Yee}{ping@lfs.org}
+
+The list methods make it very easy to use a list as a stack, where the
+last element added is the first element retrieved (``last-in,
+first-out'').  To add an item to the top of the stack, use
+\method{append()}.  To retrieve an item from the top of the stack, use
+\method{pop()} without an explicit index.  For example:
+
+\begin{verbatim}
+>>> stack = [3, 4, 5]
+>>> stack.append(6)
+>>> stack.append(7)
+>>> stack
+[3, 4, 5, 6, 7]
+>>> stack.pop()
+7
+>>> stack
+[3, 4, 5, 6]
+>>> stack.pop()
+6
+>>> stack.pop()
+5
+>>> stack
+[3, 4]
+\end{verbatim}
+
+
+\subsection{Using Lists as Queues \label{lists-as-queues}}
+\sectionauthor{Ka-Ping Yee}{ping@lfs.org}
+
+You can also use a list conveniently as a queue, where the first
+element added is the first element retrieved (``first-in,
+first-out'').  To add an item to the back of the queue, use
+\method{append()}.  To retrieve an item from the front of the queue,
+use \method{pop()} with \code{0} as the index.  For example:
+
+\begin{verbatim}
+>>> queue = ["Eric", "John", "Michael"]
+>>> queue.append("Terry")           # Terry arrives
+>>> queue.append("Graham")          # Graham arrives
+>>> queue.pop(0)
+'Eric'
+>>> queue.pop(0)
+'John'
+>>> queue
+['Michael', 'Terry', 'Graham']
+\end{verbatim}
+
+
 \subsection{Functional Programming Tools \label{functional}}
 
 There are three built-in functions that are very useful when used with
@@ -1665,11 +1786,11 @@ If you store using a key that is already in use, the old value
 associated with that key is forgotten.  It is an error to extract a
 value using a non-existent key.
 
-The \code{keys()} method of a dictionary object returns a list of all the
-keys used in the dictionary, in random order (if you want it sorted,
-just apply the \code{sort()} method to the list of keys).  To check
-whether a single key is in the dictionary, use the \code{has_key()}
-method of the dictionary.
+The \code{keys()} method of a dictionary object returns a list of all
+the keys used in the dictionary, in random order (if you want it
+sorted, just apply the \code{sort()} method to the list of keys).  To
+check whether a single key is in the dictionary, use the
+\code{has_key()} method of the dictionary.
 
 Here is a small example using a dictionary:
 
@@ -1732,6 +1853,9 @@ expression to a variable.  For example,
 \end{verbatim}
 
 Note that in Python, unlike C, assignment cannot occur inside expressions.
+C programmers may grumble about this, but it avoids a common class of
+problems encountered in C programs: typing \code{=} in an expression when
+\code{==} was intended.
 
 \section{Comparing Sequences and Other Types \label{comparing}}
 
@@ -1847,9 +1971,10 @@ If you intend to use a function often you can assign it to a local name:
 \section{More on Modules \label{moreModules}}
 
 A module can contain executable statements as well as function
-definitions.  These statements are intended to initialize the module.
-They are executed only the \emph{first} time the module is imported
-somewhere.\footnote{
+definitions.
+These statements are intended to initialize the module.
+They are executed only the
+\emph{first} time the module is imported somewhere.\footnote{
         In fact function definitions are also `statements' that are
         `executed'; the execution enters the function name in the
         module's global symbol table.
@@ -1865,18 +1990,14 @@ module's global variables with the same notation used to refer to its
 functions,
 \code{modname.itemname}.
 
-Modules can import other modules.
-It is customary but not required to place all
-\code{import}
-statements at the beginning of a module (or script, for that matter).
-The imported module names are placed in the importing module's global
-symbol table.
-
-There is a variant of the
-\code{import}
-statement that imports names from a module directly into the importing
-module's symbol table.
-For example:
+Modules can import other modules.  It is customary but not required to
+place all \keyword{import} statements at the beginning of a module (or
+script, for that matter).  The imported module names are placed in the
+importing module's global symbol table.
+
+There is a variant of the \keyword{import} statement that imports
+names from a module directly into the importing module's symbol
+table.  For example:
 
 \begin{verbatim}
 >>> from fibo import fib, fib2
@@ -1927,17 +2048,18 @@ use a lot of standard modules, if a file called \file{spam.pyc} exists
 in the directory where \file{spam.py} is found, this is assumed to
 contain an already-``byte-compiled'' version of the module \module{spam}.
 The modification time of the version of \file{spam.py} used to create
-\file{spam.pyc} is recorded in \file{spam.pyc}, and the file is
-ignored if these don't match.
-
-Normally, you don't need to do anything to create the \file{spam.pyc} file.
-Whenever \file{spam.py} is successfully compiled, an attempt is made to
-write the compiled version to \file{spam.pyc}.  It is not an error if
-this attempt fails; if for any reason the file is not written
-completely, the resulting \file{spam.pyc} file will be recognized as
-invalid and thus ignored later.  The contents of the \file{spam.pyc}
-file is platform independent, so a Python module directory can be
-shared by machines of different architectures.
+\file{spam.pyc} is recorded in \file{spam.pyc}, and the
+\file{.pyc} file is ignored if these don't match.
+
+Normally, you don't need to do anything to create the
+\file{spam.pyc} file.  Whenever \file{spam.py} is successfully
+compiled, an attempt is made to write the compiled version to
+\file{spam.pyc}.  It is not an error if this attempt fails; if for any
+reason the file is not written completely, the resulting
+\file{spam.pyc} file will be recognized as invalid and thus ignored
+later.  The contents of the \file{spam.pyc} file are platform
+independent, so a Python module directory can be shared by machines of
+different architectures.
 
 Some tips for experts:
 
@@ -1962,10 +2084,10 @@ programs may rely on having these available, you should only use this
 option if you know what you're doing.
 
 \item
-A program doesn't run any faster when it is read from a
-\file{.pyc} or \file{.pyo} file than when it is read from a \file{.py}
-file; the only thing that's faster about \file{.pyc} or \file{.pyo}
-files is the speed with which they are loaded.
+A program doesn't run any faster when it is read from a \file{.pyc} or
+\file{.pyo} file than when it is read from a \file{.py} file; the only
+thing that's faster about \file{.pyc} or \file{.pyo} files is the
+speed with which they are loaded.
 
 \item
 When a script is run by giving its name on the command line, the
@@ -2085,8 +2207,8 @@ by using ``dotted module names''.  For example, the module name
 \samp{A}.  Just like the use of modules saves the authors of different
 modules from having to worry about each other's global variable names,
 the use of dotted module names saves the authors of multi-module
-packages like NumPy or PIL from having to worry about each other's
-module names.
+packages like NumPy or the Python Imaging Library from having to worry
+about each other's module names.
 
 Suppose you want to design a collection of modules (a ``package'') for
 the uniform handling of sound files and sound data.  There are many
@@ -2165,18 +2287,19 @@ from Sound.Effects.echo import echofilter
 \end{verbatim}
 
 Again, this loads the submodule \module{echo}, but this makes its function
-echofilter directly available:
+\function{echofilter()} directly available:
 
 \begin{verbatim}
 echofilter(input, output, delay=0.7, atten=4)
 \end{verbatim}
 
 Note that when using \code{from \var{package} import \var{item}}, the
-item can be either a submodule (or subpackage) of the package, or some
+item can be either a submodule (or subpackage) of the package, or some 
 other name defined in the package, like a function, class or
 variable.  The \code{import} statement first tests whether the item is
 defined in the package; if not, it assumes it is a module and attempts
-to load it.  If it fails to find it, \exception{ImportError} is raised.
+to load it.  If it fails to find it, an
+\exception{ImportError} exception is raised.
 
 Contrarily, when using syntax like \code{import
 \var{item.subitem.subsubitem}}, each item except for the last must be
@@ -2201,14 +2324,14 @@ problem for long module names.
 
 The only solution is for the package author to provide an explicit
 index of the package.  The import statement uses the following
-convention: if a package's \file{__init__.py} code defines a list named
-\code{__all__}, it is taken to be the list of module names that should be imported
-when \code{from \var{package} import *} is
+convention: if a package's \file{__init__.py} code defines a list
+named \code{__all__}, it is taken to be the list of module names that
+should be imported when \code{from \var{package} import *} is
 encountered.  It is up to the package author to keep this list
 up-to-date when a new version of the package is released.  Package
 authors may also decide not to support it, if they don't see a use for
 importing * from their package.  For example, the file
-\code{Sounds/Effects/__init__.py} could contain the following code:
+\file{Sounds/Effects/__init__.py} could contain the following code:
 
 \begin{verbatim}
 __all__ = ["echo", "surround", "reverse"]
@@ -2235,9 +2358,9 @@ from Sound.Effects import *
 
 
 In this example, the echo and surround modules are imported in the
-current namespace because they are defined in the \module{Sound.Effects}
-package when the \code{from...import} statement is executed.  (This also
-works when \code{__all__} is defined.)
+current namespace because they are defined in the
+\module{Sound.Effects} package when the \code{from...import} statement
+is executed.  (This also works when \code{__all__} is defined.)
 
 Note that in general the practicing of importing * from a module or
 package is frowned upon, since it often causes poorly readable code.
@@ -2263,11 +2386,12 @@ found in the current package (the package of which the current module
 is a submodule), the \code{import} statement looks for a top-level module
 with the given name.
 
-When packages are structured into subpackages (as with the \module{Sound}
-package in the example), there's no shortcut to refer to submodules of
-sibling packages - the full name of the subpackage must be used.  For
-example, if the module \module{Sound.Filters.vocoder} needs to use the \module{echo}
-module in the \module{Sound.Effects} package, it can use \code{from
+When packages are structured into subpackages (as with the
+\module{Sound} package in the example), there's no shortcut to refer
+to submodules of sibling packages - the full name of the subpackage
+must be used.  For example, if the module
+\module{Sound.Filters.vocoder} needs to use the \module{echo} module
+in the \module{Sound.Effects} package, it can use \code{from
 Sound.Effects import echo}.
 
 %(One could design a notation to refer to parent packages, similar to
@@ -2302,12 +2426,12 @@ your output; the first way is to do all the string handling yourself;
 using string slicing and concatenation operations you can create any
 lay-out you can imagine.  The standard module
 \module{string}\refstmodindex{string} contains some useful operations
-for padding strings to a given column width;
-these will be discussed shortly.  The second way is to use the
-\code{\%} operator with a string as the left argument.  \code{\%}
-interprets the left argument as a C \cfunction{sprintf()}-style
-format string to be applied to the right argument, and returns the
-string resulting from this formatting operation.
+for padding strings to a given column width; these will be discussed
+shortly.  The second way is to use the \code{\%} operator with a
+string as the left argument.  The \code{\%} operator interprets the
+left argument as a C much like a \cfunction{sprintf()}-style format
+string to be applied to the right argument, and returns the string
+resulting from this formatting operation.
 
 One question remains, of course: how do you convert values to strings?
 Luckily, Python has a way to convert any value to a string: pass it to
@@ -2409,7 +2533,7 @@ If there is more than one format in the string you pass a tuple as
 right operand, e.g.
 
 \begin{verbatim}
->>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
+>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
 >>> for name, phone in table.items():
 ...     print '%-10s ==> %10d' % (name, phone)
 ... 
@@ -2532,11 +2656,11 @@ position in the file, measured in bytes from the beginning of the
 file.  To change the file object's position, use
 \samp{f.seek(\var{offset}, \var{from_what})}.  The position is
 computed from adding \var{offset} to a reference point; the reference
-point is selected by the \var{from_what} argument.  A \var{from_what}
-value of 0 measures from the beginning of the file, 1 uses the current
-file position, and 2 uses the end of the file as the reference point.
-\var{from_what} can be omitted and defaults to 0, using the beginning
-of the file as the reference point.
+point is selected by the \var{from_what} argument.  A
+\var{from_what} value of 0 measures from the beginning of the file, 1
+uses the current file position, and 2 uses the end of the file as the
+reference point.  \var{from_what} can be omitted and defaults to 0,
+using the beginning of the file as the reference point.
 
 \begin{verbatim}
 >>> f=open('/tmp/workfile', 'r+')
@@ -2561,9 +2685,10 @@ Traceback (innermost last):
 ValueError: I/O operation on closed file
 \end{verbatim}
 
-File objects have some additional methods, such as \method{isatty()}
-and \method{truncate()} which are less frequently used; consult the
-Library Reference for a complete guide to file objects.
+File objects have some additional methods, such as
+\method{isatty()} and \method{truncate()} which are less frequently
+used; consult the Library Reference for a complete guide to file
+objects.
 
 \subsection{The \module{pickle} Module \label{pickle}}
 \refstmodindex{pickle}
@@ -2605,12 +2730,12 @@ x = pickle.load(f)
 when you don't want to write the pickled data to a file; consult the
 complete documentation for \module{pickle} in the Library Reference.)
 
-\module{pickle} is the standard way to make Python objects which can be
-stored and reused by other programs or by a future invocation of the
-same program; the technical term for this is a \dfn{persistent}
-object.  Because \module{pickle} is so widely used, many authors who
-write Python extensions take care to ensure that new data types such
-as matrices can be properly pickled and unpickled.
+\module{pickle} is the standard way to make Python objects which can
+be stored and reused by other programs or by a future invocation of
+the same program; the technical term for this is a
+\dfn{persistent} object.  Because \module{pickle} is so widely used,
+many authors who write Python extensions take care to ensure that new
+data types such as matrices can be properly pickled and unpickled.
 
 
 
@@ -2618,8 +2743,8 @@ as matrices can be properly pickled and unpickled.
 
 Until now error messages haven't been more than mentioned, but if you
 have tried out the examples you have probably seen some.  There are
-(at least) two distinguishable kinds of errors: \emph{syntax errors}
-and \emph{exceptions}.
+(at least) two distinguishable kinds of errors:
+\emph{syntax errors} and \emph{exceptions}.
 
 \section{Syntax Errors \label{syntaxErrors}}
 
@@ -2635,13 +2760,12 @@ SyntaxError: invalid syntax
 \end{verbatim}
 
 The parser repeats the offending line and displays a little `arrow'
-pointing at the earliest point in the line where the error was detected.
-The error is caused by (or at least detected at) the token
-\emph{preceding}
-the arrow: in the example, the error is detected at the keyword
-\keyword{print}, since a colon (\character{:}) is missing before it.
-File name and line number are printed so you know where to look in case
-the input came from a script.
+pointing at the earliest point in the line where the error was
+detected.  The error is caused by (or at least detected at) the token
+\emph{preceding} the arrow: in the example, the error is detected at
+the keyword \keyword{print}, since a colon (\character{:}) is missing
+before it.  File name and line number are printed so you know where to
+look in case the input came from a script.
 
 \section{Exceptions \label{exceptions}}
 
@@ -2670,9 +2794,7 @@ TypeError: illegal argument type for built-in operation
 The last line of the error message indicates what happened.
 Exceptions come in different types, and the type is printed as part of
 the message: the types in the example are
-\exception{ZeroDivisionError},
-\exception{NameError}
-and
+\exception{ZeroDivisionError}, \exception{NameError} and
 \exception{TypeError}.
 The string printed as the exception type is the name of the built-in
 name for the exception that occurred.  This is true for all built-in
@@ -2689,59 +2811,61 @@ exception happened, in the form of a stack backtrace.
 In general it contains a stack backtrace listing source lines; however,
 it will not display lines read from standard input.
 
-The Library Reference lists the built-in exceptions and their
-meanings.
+The \emph{Python Library Reference} lists the built-in exceptions and
+their meanings.
+
 
 \section{Handling Exceptions \label{handling}}
 
 It is possible to write programs that handle selected exceptions.
-Look at the following example, which prints a table of inverses of
-some floating point numbers:
+Look at the following example, which asks the user for input until a
+valid integer has been entered, but allows the user to interrupt the
+program (using \kbd{Control-C} or whatever the operating system
+supports); note that a user-generated interruption is signalled by
+raising the \exception{KeyboardInterrupt} exception.
 
 \begin{verbatim}
->>> numbers = [0.3333, 2.5, 0, 10]
->>> for x in numbers:
-...     print x,
+>>> while 1:
 ...     try:
-...         print 1.0 / x
-...     except ZeroDivisionError:
-...         print '*** has no inverse ***'
+...         x = int(raw_input("Please enter a number: "))
+...         break
+...     except ValueError:
+...         print "Oops! That was no valid number.  Try again..."
 ...     
-0.3333 3.00030003
-2.5 0.4
-0 *** has no inverse ***
-10 0.1
 \end{verbatim}
 
 The \keyword{try} statement works as follows.
+
 \begin{itemize}
 \item
-First, the \emph{try clause}
-(the statement(s) between the \keyword{try} and \keyword{except}
-keywords) is executed.
+First, the \emph{try clause} (the statement(s) between the
+\keyword{try} and \keyword{except} keywords) is executed.
+
 \item
-If no exception occurs, the
-\emph{except\ clause}
-is skipped and execution of the \keyword{try} statement is finished.
+If no exception occurs, the \emph{except\ clause} is skipped and
+execution of the \keyword{try} statement is finished.
+
 \item
-If an exception occurs during execution of the try clause,
-the rest of the clause is skipped.  Then if its type matches the
-exception named after the \keyword{except} keyword, the rest of the
-try clause is skipped, the except clause is executed, and then
-execution continues after the \keyword{try} statement.
+If an exception occurs during execution of the try clause, the rest of
+the clause is skipped.  Then if its type matches the exception named
+after the \keyword{except} keyword, the rest of the try clause is
+skipped, the except clause is executed, and then execution continues
+after the \keyword{try} statement.
+
 \item
 If an exception occurs which does not match the exception named in the
 except clause, it is passed on to outer \keyword{try} statements; if
-no handler is found, it is an \emph{unhandled exception}
-and execution stops with a message as shown above.
+no handler is found, it is an \emph{unhandled exception} and execution
+stops with a message as shown above.
+
 \end{itemize}
+
 A \keyword{try} statement may have more than one except clause, to
-specify handlers for different exceptions.
-At most one handler will be executed.
-Handlers only handle exceptions that occur in the corresponding try
-clause, not in other handlers of the same \keyword{try} statement.
-An except clause may name multiple exceptions as a parenthesized list,
-e.g.:
+specify handlers for different exceptions.  At most one handler will
+be executed.  Handlers only handle exceptions that occur in the
+corresponding try clause, not in other handlers of the same
+\keyword{try} statement. An except clause may name multiple exceptions
+as a parenthesized list, e.g.:
 
 \begin{verbatim}
 ... except (RuntimeError, TypeError, NameError):
@@ -2749,13 +2873,26 @@ e.g.:
 \end{verbatim}
 
 The last except clause may omit the exception name(s), to serve as a
-wildcard.
-Use this with extreme caution, since it is easy to mask a real
-programming error in this way!
+wildcard.  Use this with extreme caution, since it is easy to mask a
+real programming error in this way!  It can also be used to print an
+error message and then re-raise the exception (allowing a caller to
+handle the exception as well):
 
-Each exception clause must have at least one line of executable code 
-in the block.  Comments are not executable code.  If you want the 
-exception clause to do nothing, use the \keyword{pass} statement.
+\begin{verbatim}
+import string, sys
+
+try:
+    f = open('myfile.txt')
+    s = f.readline()
+    i = int(string.strip(s))
+except IOError, (errno, strerror):
+    print "I/O error(%s): %s" % (errno, strerror)
+except ValueError:
+    print "Could not convert data to an integer."
+except:
+    print "Unexpected error:", sys.exc_info()[0]
+    raise
+\end{verbatim}
 
 The \keyword{try} \ldots\ \keyword{except} statement has an optional
 \emph{else clause}, which must follow all except clauses.  It is
@@ -2832,26 +2969,33 @@ argument.
 \section{User-defined Exceptions \label{userExceptions}}
 
 Programs may name their own exceptions by assigning a string to a
-variable.
-For example:
+variable or creating a new exception class.  For example:
 
 \begin{verbatim}
->>> my_exc = 'my_exc'
+>>> class MyError:
+...     def __init__(self, value):
+...         self.value = value
+...     def __str__(self):
+...         return `self.value`
+... 
 >>> try:
-...     raise my_exc, 2*2
-... except my_exc, val:
-...     print 'My exception occurred, value:', val
+...     raise MyError(2*2)
+... except MyError, e:
+...     print 'My exception occurred, value:', e.value
 ... 
 My exception occurred, value: 4
->>> raise my_exc, 1
+>>> raise MyError, 1
 Traceback (innermost last):
   File "<stdin>", line 1
-my_exc: 1
+__main__.MyError: 1
 \end{verbatim}
 
 Many standard modules use this to report errors that may occur in
 functions they define.
 
+More information on classes is presented in chapter \ref{classes},
+``Classes.''
+
 
 \section{Defining Clean-up Actions \label{cleanup}}
 
@@ -2901,8 +3045,8 @@ method function is declared with an explicit first argument
 representing the object, which is provided implicitly by the call.  As
 in Smalltalk, classes themselves are objects, albeit in the wider
 sense of the word: in Python, all data types are objects.  This
-provides semantics for importing and renaming.  But, just like in \Cpp{}
-or Modula-3, built-in types cannot be used as base classes for
+provides semantics for importing and renaming.  But, just like in
+\Cpp{} or Modula-3, built-in types cannot be used as base classes for
 extension by the user.  Also, like in \Cpp{} but unlike in Modula-3, most
 built-in operators with special syntax (arithmetic operators,
 subscripting etc.) can be redefined for class instances.
@@ -3061,10 +3205,10 @@ class ClassName:
     <statement-N>
 \end{verbatim}
 
-Class definitions, like function definitions (\keyword{def}
-statements) must be executed before they have any effect.  (You could
-conceivably place a class definition in a branch of an \keyword{if}
-statement, or inside a function.)
+Class definitions, like function definitions
+(\keyword{def} statements) must be executed before they have any
+effect.  (You could conceivably place a class definition in a branch
+of an \keyword{if} statement, or inside a function.)
 
 In practice, the statements inside a class definition will usually be
 function definitions, but other statements are allowed, and sometimes
@@ -3107,15 +3251,15 @@ class MyClass:
 \end{verbatim}
 
 then \code{MyClass.i} and \code{MyClass.f} are valid attribute
-references, returning an integer and a function object, respectively.
+references, returning an integer and a method object, respectively.
 Class attributes can also be assigned to, so you can change the value
-of \code{MyClass.i} by assignment.  \code{__doc__} is also a valid
-attribute that's read-only, returning the docstring belonging to
-the class: \code{"A simple example class"}).  
+of \code{MyClass.i} by assignment.  \member{__doc__} is also a valid
+attribute, returning the docstring belonging to the class: \code{"A
+simple example class"}). 
 
 Class \emph{instantiation} uses function notation.  Just pretend that
 the class object is a parameterless function that returns a new
-instance of the class.  For example, (assuming the above class):
+instance of the class.  For example (assuming the above class):
 
 \begin{verbatim}
 x = MyClass()
@@ -3124,6 +3268,41 @@ x = MyClass()
 creates a new \emph{instance} of the class and assigns this object to
 the local variable \code{x}.
 
+The instantiation operation (``calling'' a class object) creates an
+empty object.  Many classes like to create objects in a known initial
+state.  Therefore a class may define a special method named
+\method{__init__()}, like this:
+
+\begin{verbatim}
+    def __init__(self):
+        self.data = []
+\end{verbatim}
+
+When a class defines an \method{__init__()} method, class
+instantiation automatically invokes \method{__init__()} for the
+newly-created class instance.  So in this example, a new, initialized
+instance can be obtained by:
+
+\begin{verbatim}
+x = MyClass()
+\end{verbatim}
+
+Of course, the \method{__init__()} method may have arguments for
+greater flexibility.  In that case, arguments given to the class
+instantiation operator are passed on to \method{__init__()}.  For
+example,
+
+\begin{verbatim}
+>>> class Complex:
+...     def __init__(self, realpart, imagpart):
+...         self.r = realpart
+...         self.i = imagpart
+... 
+>>> x = Complex(3.0,-4.5)
+>>> x.r, x.i
+(3.0, -4.5)
+\end{verbatim}
+
 
 \subsection{Instance Objects \label{instanceObjects}}
 
@@ -3161,9 +3340,8 @@ objects define corresponding methods of its instances.  So in our
 example, \code{x.f} is a valid method reference, since
 \code{MyClass.f} is a function, but \code{x.i} is not, since
 \code{MyClass.i} is not.  But \code{x.f} is not the same thing as
-\code{MyClass.f} --- it is a \emph{method object}, not a function
-object.%
-\obindex{method}
+\code{MyClass.f} --- it is a \obindex{method}\emph{method object}, not
+a function object.
 
 
 \subsection{Method Objects \label{methodObjects}}
@@ -3290,7 +3468,7 @@ Methods may call other methods by using method attributes of the
 
 \begin{verbatim}
 class Bag:
-    def empty(self):
+    def __init__(self):
         self.data = []
     def add(self, x):
         self.data.append(x)
@@ -3300,41 +3478,6 @@ class Bag:
 \end{verbatim}
 
 
-The instantiation operation (``calling'' a class object) creates an
-empty object.  Many classes like to create objects in a known initial
-state.  Therefore a class may define a special method named
-\method{__init__()}, like this:
-
-\begin{verbatim}
-    def __init__(self):
-        self.empty()
-\end{verbatim}
-
-When a class defines an \method{__init__()} method, class
-instantiation automatically invokes \method{__init__()} for the
-newly-created class instance.  So in the \class{Bag} example, a new
-and initialized instance can be obtained by:
-
-\begin{verbatim}
-x = Bag()
-\end{verbatim}
-
-Of course, the \method{__init__()} method may have arguments for
-greater flexibility.  In that case, arguments given to the class
-instantiation operator are passed on to \method{__init__()}.  For
-example,
-
-\begin{verbatim}
->>> class Complex:
-...     def __init__(self, realpart, imagpart):
-...         self.r = realpart
-...         self.i = imagpart
-... 
->>> x = Complex(3.0,-4.5)
->>> x.r, x.i
-(3.0, -4.5)
-\end{verbatim}
-
 Methods may reference global names in the same way as ordinary
 functions.  The global scope associated with a method is the module
 containing the class definition.  (The class itself is never used as a
@@ -3389,7 +3532,7 @@ methods have no special privileges when calling other methods of the
 same object, a method of a base class that calls another method
 defined in the same base class, may in fact end up calling a method of
 a derived class that overrides it.  (For \Cpp{} programmers: all methods
-in Python are ``virtual functions''.)
+in Python are effectively \keyword{virtual}.)
 
 An overriding method in a derived class may in fact want to extend
 rather than simply replace the base class method of the same name.
@@ -3495,7 +3638,7 @@ class VirtualAttributes:
 
 %\emph{Warning: this is an experimental feature.}  To avoid all
 %potential problems, refrain from using identifiers starting with
-%double underscore except for predefined uses like \code{__init__}.  To
+%double underscore except for predefined uses like \samp{__init__}.  To
 %use private names while maintaining future compatibility: refrain from
 %using the same private name in classes related via subclassing; avoid
 %explicit (manual) mangling/unmangling; and assume that at some point
@@ -3558,8 +3701,9 @@ raise Class, instance
 raise instance
 \end{verbatim}
 
-In the first form, \code{instance} must be an instance of \class{Class}
-or of a class derived from it.  The second form is a shorthand for
+In the first form, \code{instance} must be an instance of
+\class{Class} or of a class derived from it.  The second form is a
+shorthand for:
 
 \begin{verbatim}
 raise instance.__class__, instance
@@ -3739,10 +3883,9 @@ indented continuation lines...)
 
 Automatic completion of variable and module names is optionally
 available.  To enable it in the interpreter's interactive mode, add
-the following to your \file{\$HOME/.pythonrc.py} file:% $ <- bow to font-lock
+the following to your \file{\$HOME/.pythonrc.py} file:%
 \indexii{.pythonrc.py}{file}
-\refstmodindex{rlcompleter}
-\refbimodindex{readline}
+\refstmodindex{rlcompleter}\refbimodindex{readline}
 
 \begin{verbatim}
 import rlcompleter, readline