Merge in changes from the 1.5.2p2 release.
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 @@
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 @@
\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 @@
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 @@
>>>
\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 @@
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 @@
\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 @@
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 @@
>>> width * height
900
\end{verbatim}
-%
+
A value can be assigned to several variables simultaneously:
\begin{verbatim}
@@ -557,8 +567,8 @@
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 @@
'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 @@
'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 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 @@
\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 @@
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 @@
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 @@
\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 @@
...
\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 @@
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 @@
\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 @@
[-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 @@
4 lamb
\end{verbatim}
+
\section{\keyword{break} and \keyword{continue} Statements, and
\keyword{else} Clauses on Loops
\label{break}}
@@ -1062,13 +1099,15 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
\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 @@
\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 @@
[-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 @@
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 @@
\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 @@
\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 @@
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.
+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
-\code{import}
-statement that imports names from a module directly into the importing
-module's symbol table.
-For example:
+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 @@
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.
+\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 is platform independent, so a Python module directory can be
-shared by machines of different architectures.
+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 @@
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 @@
\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 @@
\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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
\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 @@
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 @@
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 @@
\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 @@
\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 @@
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 @@
<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 @@
\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 @@
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 @@
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 @@
\begin{verbatim}
class Bag:
- def empty(self):
+ def __init__(self):
self.data = []
def add(self, x):
self.data.append(x)
@@ -3300,41 +3478,6 @@
\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 @@
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 @@
%\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 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 @@
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