Lots of small changes collected over months...
diff --git a/Doc/Makefile b/Doc/Makefile
index 64b029e..e55871b 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -31,7 +31,7 @@
bibtex qua
latex qua
latex qua
- dvips lib >qua.ps
+ dvips qua >qua.ps
libinfo:
@echo This may take a while...
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index 96eaa1d..2d3b1e8 100644
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -290,10 +290,17 @@
\begin{description}
\item[Dictionaries]
-These represent finite sets of objects indexed by strings.
+These represent finite sets of objects indexed by almost arbitrary
+values. The only types of values not acceptable as keys are values
+containing lists or dictionaries or other mutable types that are
+compared by value rather than by object identity --- the reason being
+that the implementation requires that a key's hash value be constant.
+Numeric types used for keys obey the normal rules for numeric
+comparison: if two numbers compare equal (e.g. 1 and 1.0) then they
+can be used interchangeably to index the same dictionary entry.
+
Dictionaries are mutable; they are created by the \verb\{...}\
-notation (see section \ref{dict}). (Implementation note: the strings
-used for indexing must not contain null bytes.)
+notation (see section \ref{dict}).
\obindex{dictionary}
\obindex{mutable}
@@ -409,7 +416,7 @@
\obindex{instance}
\indexii{class object}{call}
\index{container}
-\index{dictionary}
+\obindex{dictionary}
\indexii{class}{attribute}
Class attribute assignments update the class's dictionary, never the
@@ -589,12 +596,30 @@
Called by the \verb\print\ statement and conversions (reverse quotes) to
compute the string representation of an object.
-\item[\tt _cmp__(self, other)]
+\item[\tt __cmp__(self, other)]
Called by all comparison operations. Should return -1 if
\verb\self < other\, 0 if \verb\self == other\, +1 if
-\verb\self > other\. (Implementation note: due to limitations in the
-interpreter, exceptions raised by comparisons are ignored, and the
-objects will be considered equal in this case.)
+\verb\self > other\. If no \code{__cmp__} operation is defined, class
+instances are compared by object identity (``address'').
+(Implementation note: due to limitations in the interpreter,
+exceptions raised by comparisons are ignored, and the objects will be
+considered equal in this case.)
+
+\item[\tt __hash__(self)]
+Called by dictionary operations and by the built-in function
+\code{hash()}. Should return a 32-bit integer usable as a hash value
+for dictionary operations. The only required property is that objects
+which compare equal have the same hash value; it is advised to somehow
+mix together (e.g. using exclusing or) the hash values for the
+components of the object that also play a part in comparison of
+objects. If a class does not define a \code{__cmp__} method it should
+not define a \code{__hash__} operation either; if it defines
+\code{__cmp__} but not \code{__hash__} its instances will not be
+usable as dictionary keys. If a class defines mutable objects and
+implements a \code{__cmp__} method it should not implement
+\code{__hash__}, since the dictionary implementation assumes that a
+key's hash value is a constant.
+\obindex{dictionary}
\end{description}
diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex
index 7857e95..59ba90a 100644
--- a/Doc/ref/ref5.tex
+++ b/Doc/ref/ref5.tex
@@ -176,8 +176,9 @@
entries of the dictionary: each key object is used as a key into the
dictionary to store the corresponding datum.
-Keys must be strings, otherwise a \verb\TypeError\ exception is
-raised. Clashes between duplicate keys are not detected; the last
+Restrictions on the types of the key values are listed earlier in
+section \ref{types}.
+Clashes between duplicate keys are not detected; the last
datum (textually rightmost in the display) stored for a given key
value prevails.
\exindex{TypeError}
@@ -565,10 +566,10 @@
Mappings (dictionaries) are compared through lexicographic
comparison of their sorted (key, value) lists.%
\footnote{This is expensive since it requires sorting the keys first,
-but about the only sensible definition. It was tried to compare
-dictionaries by identity only, but this caused surprises because
-people expected to be able to test a dictionary for emptiness by
-comparing it to {\tt \{\}}.}
+but about the only sensible definition. An earlier version of Python
+compared dictionaries by identity only, but this caused surprises
+because people expected to be able to test a dictionary for emptiness
+by comparing it to {\tt \{\}}.}
\item
Most other types compare unequal unless they are the same object;
diff --git a/Doc/ref3.tex b/Doc/ref3.tex
index 96eaa1d..2d3b1e8 100644
--- a/Doc/ref3.tex
+++ b/Doc/ref3.tex
@@ -290,10 +290,17 @@
\begin{description}
\item[Dictionaries]
-These represent finite sets of objects indexed by strings.
+These represent finite sets of objects indexed by almost arbitrary
+values. The only types of values not acceptable as keys are values
+containing lists or dictionaries or other mutable types that are
+compared by value rather than by object identity --- the reason being
+that the implementation requires that a key's hash value be constant.
+Numeric types used for keys obey the normal rules for numeric
+comparison: if two numbers compare equal (e.g. 1 and 1.0) then they
+can be used interchangeably to index the same dictionary entry.
+
Dictionaries are mutable; they are created by the \verb\{...}\
-notation (see section \ref{dict}). (Implementation note: the strings
-used for indexing must not contain null bytes.)
+notation (see section \ref{dict}).
\obindex{dictionary}
\obindex{mutable}
@@ -409,7 +416,7 @@
\obindex{instance}
\indexii{class object}{call}
\index{container}
-\index{dictionary}
+\obindex{dictionary}
\indexii{class}{attribute}
Class attribute assignments update the class's dictionary, never the
@@ -589,12 +596,30 @@
Called by the \verb\print\ statement and conversions (reverse quotes) to
compute the string representation of an object.
-\item[\tt _cmp__(self, other)]
+\item[\tt __cmp__(self, other)]
Called by all comparison operations. Should return -1 if
\verb\self < other\, 0 if \verb\self == other\, +1 if
-\verb\self > other\. (Implementation note: due to limitations in the
-interpreter, exceptions raised by comparisons are ignored, and the
-objects will be considered equal in this case.)
+\verb\self > other\. If no \code{__cmp__} operation is defined, class
+instances are compared by object identity (``address'').
+(Implementation note: due to limitations in the interpreter,
+exceptions raised by comparisons are ignored, and the objects will be
+considered equal in this case.)
+
+\item[\tt __hash__(self)]
+Called by dictionary operations and by the built-in function
+\code{hash()}. Should return a 32-bit integer usable as a hash value
+for dictionary operations. The only required property is that objects
+which compare equal have the same hash value; it is advised to somehow
+mix together (e.g. using exclusing or) the hash values for the
+components of the object that also play a part in comparison of
+objects. If a class does not define a \code{__cmp__} method it should
+not define a \code{__hash__} operation either; if it defines
+\code{__cmp__} but not \code{__hash__} its instances will not be
+usable as dictionary keys. If a class defines mutable objects and
+implements a \code{__cmp__} method it should not implement
+\code{__hash__}, since the dictionary implementation assumes that a
+key's hash value is a constant.
+\obindex{dictionary}
\end{description}
diff --git a/Doc/ref5.tex b/Doc/ref5.tex
index 7857e95..59ba90a 100644
--- a/Doc/ref5.tex
+++ b/Doc/ref5.tex
@@ -176,8 +176,9 @@
entries of the dictionary: each key object is used as a key into the
dictionary to store the corresponding datum.
-Keys must be strings, otherwise a \verb\TypeError\ exception is
-raised. Clashes between duplicate keys are not detected; the last
+Restrictions on the types of the key values are listed earlier in
+section \ref{types}.
+Clashes between duplicate keys are not detected; the last
datum (textually rightmost in the display) stored for a given key
value prevails.
\exindex{TypeError}
@@ -565,10 +566,10 @@
Mappings (dictionaries) are compared through lexicographic
comparison of their sorted (key, value) lists.%
\footnote{This is expensive since it requires sorting the keys first,
-but about the only sensible definition. It was tried to compare
-dictionaries by identity only, but this caused surprises because
-people expected to be able to test a dictionary for emptiness by
-comparing it to {\tt \{\}}.}
+but about the only sensible definition. An earlier version of Python
+compared dictionaries by identity only, but this caused surprises
+because people expected to be able to test a dictionary for emptiness
+by comparing it to {\tt \{\}}.}
\item
Most other types compare unequal unless they are the same object;
diff --git a/Doc/tut.tex b/Doc/tut.tex
index 2535808..a51fb83 100644
--- a/Doc/tut.tex
+++ b/Doc/tut.tex
@@ -183,6 +183,12 @@
usually what you want) they are satisfied from whatever file or device
is connected to standard input of the Python interpreter.
+When a script file is used, it is sometimes useful to be able to run
+the script and enter interactive mode afterwards. This can be done by
+passing {\tt -i} before the script. (This does not work if the script
+is read from standard input, for the same reason as explained in the
+previous paragraph.)
+
\subsection{Argument Passing}
When known to the interpreter, the script name and additional
@@ -211,8 +217,8 @@
\bcode\begin{verbatim}
python
-Python 0.9.7 (Aug 28 1992).
-Copyright 1990, 1991, 1992 Stichting Mathematisch Centrum, Amsterdam
+Python 0.9.9 (Apr 2 1993).
+Copyright 1990, 1991, 1992, 1993 Stichting Mathematisch Centrum, Amsterdam
>>>
\end{verbatim}\ecode
@@ -1748,58 +1754,44 @@
\bcode\small\begin{verbatim}
>>> 10 * (1/0)
-Unhandled exception: run-time error: integer division by zero
Stack backtrace (innermost last):
File "<stdin>", line 1
+ZeroDivisionError: integer division or modulo
>>> 4 + foo*3
-Unhandled exception: undefined name: foo
Stack backtrace (innermost last):
File "<stdin>", line 1
+NameError: foo
>>> '2' + 2
-Unhandled exception: type error: illegal argument type for built-in operation
Stack backtrace (innermost last):
File "<stdin>", line 1
+TypeError: illegal argument type for built-in operation
>>>
\end{verbatim}\ecode
%
-The first line of the error message indicates what happened.
+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
-{\tt run-time error},
-{\tt undefined name}
+{\tt ZeroDivisionError},
+{\tt NameError}
and
-{\tt type error}.
-The rest of the line is a detail whose interpretation depends on the
-exception type.
+{\tt 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
+exceptions, but need not be true for user-defined exceptions (although
+it is a useful convention).
+Standard exception names are built-in identifiers (not reserved
+keywords).
-The rest of the error message shows the context where the
-exception happened.
+The rest of the line is a detail whose interpretation depends on the
+exception type; its meaning is dependent on the exception type.
+
+The preceding part of the error message shows the context where the
+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.
-Here is a summary of the most common exceptions:
-\begin{itemize}
-\item
-{\em Run-time\ errors}
-are generally caused by wrong data used by the program; this can be the
-programmer's fault or caused by bad input.
-The detail states the cause of the error in more detail.
-\item
-{\em Undefined\ name}
-errors are more serious: these are usually caused by misspelled
-identifiers.%
-\footnote{
- The parser does not check whether names used in a program are at
- all defined elsewhere in the program; such checks are
- postponed until run-time. The same holds for type checking.
-}
-The detail is the offending identifier.
-\item
-{\em Type\ errors} are also pretty serious: this is another case of
-using wrong data (or better, using data the wrong way), but here the
-error can be gleaned from the object type(s) alone. The detail shows
-in what context the error was detected.
-\end{itemize}
+The Python library reference manual lists the built-in exceptions and
+their meanings.
\section{Handling Exceptions}
@@ -1813,7 +1805,7 @@
... print x,
... try:
... print 1.0 / x
-... except RuntimeError:
+... except ZeroDivisionError:
... print '*** has no inverse ***'
...
0.3333 3.00030003
@@ -1862,7 +1854,8 @@
%
The last except clause may omit the exception name(s), to serve as a
wildcard.
-Use this with extreme caution!
+Use this with extreme caution, since it is easy to mask a real
+programming error in this way!
When an exception occurs, it may have an associated value, also known as
the exceptions's
@@ -1882,31 +1875,9 @@
>>>
\end{verbatim}\ecode
%
-If an exception has an argument, it is printed as the third part
+If an exception has an argument, it is printed as the last part
(`detail') of the message for unhandled exceptions.
-Standard exception names are built-in identifiers (not reserved
-keywords).
-These are in fact string objects whose
-{\em object\ identity}
-(not their value!) identifies the exceptions.
-The string is printed as the second part of the message for unhandled
-exceptions.
-Their names and values are:
-
-\bcode\begin{verbatim}
-EOFError 'end-of-file read'
-KeyboardInterrupt 'keyboard interrupt'
-MemoryError 'out of memory' *
-NameError 'undefined name' *
-RuntimeError 'run-time error' *
-SystemError 'system error' *
-TypeError 'type error' *
-\end{verbatim}\ecode
-%
-The meanings should be clear enough.
-Those exceptions with a {\tt *} in the third column have an argument.
-
Exception handlers don't just handle exceptions if they occur
immediately in the try clause, but also if they occur inside functions
that are called (even indirectly) in the try clause.
@@ -1918,10 +1889,10 @@
...
>>> try:
... this_fails()
-... except RuntimeError, detail:
+... except ZeroDivisionError, detail:
... print 'Handling run-time error:', detail
...
-Handling run-time error: integer division by zero
+Handling run-time error: integer division or modulo
>>>
\end{verbatim}\ecode
@@ -1932,10 +1903,10 @@
For example:
\bcode\begin{verbatim}
->>> raise NameError, 'Hi There!'
-Unhandled exception: undefined name: Hi There!
+>>> raise NameError, 'HiThere'
Stack backtrace (innermost last):
File "<stdin>", line 1
+NameError: HiThere
>>>
\end{verbatim}\ecode
%
@@ -1949,7 +1920,7 @@
For example:
\bcode\begin{verbatim}
->>> my_exc = 'Nobody likes me'
+>>> my_exc = 'my_exc'
>>> try:
... raise my_exc, 2*2
... except my_exc, val:
@@ -1957,9 +1928,9 @@
...
My exception occured, value: 4
>>> raise my_exc, 1
-Nobody likes me: 1
Stack backtrace (innermost last):
File "<stdin>", line 7
+my_exc: 1
>>>
\end{verbatim}\ecode
%
@@ -1979,9 +1950,9 @@
... print 'Goodbye, world!'
...
Goodbye, world!
-Unhandled exception: keyboard interrupt
Stack backtrace (innermost last):
File "<stdin>", line 2
+KeyboardInterrupt
>>>
\end{verbatim}\ecode
%
diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex
index 2535808..a51fb83 100644
--- a/Doc/tut/tut.tex
+++ b/Doc/tut/tut.tex
@@ -183,6 +183,12 @@
usually what you want) they are satisfied from whatever file or device
is connected to standard input of the Python interpreter.
+When a script file is used, it is sometimes useful to be able to run
+the script and enter interactive mode afterwards. This can be done by
+passing {\tt -i} before the script. (This does not work if the script
+is read from standard input, for the same reason as explained in the
+previous paragraph.)
+
\subsection{Argument Passing}
When known to the interpreter, the script name and additional
@@ -211,8 +217,8 @@
\bcode\begin{verbatim}
python
-Python 0.9.7 (Aug 28 1992).
-Copyright 1990, 1991, 1992 Stichting Mathematisch Centrum, Amsterdam
+Python 0.9.9 (Apr 2 1993).
+Copyright 1990, 1991, 1992, 1993 Stichting Mathematisch Centrum, Amsterdam
>>>
\end{verbatim}\ecode
@@ -1748,58 +1754,44 @@
\bcode\small\begin{verbatim}
>>> 10 * (1/0)
-Unhandled exception: run-time error: integer division by zero
Stack backtrace (innermost last):
File "<stdin>", line 1
+ZeroDivisionError: integer division or modulo
>>> 4 + foo*3
-Unhandled exception: undefined name: foo
Stack backtrace (innermost last):
File "<stdin>", line 1
+NameError: foo
>>> '2' + 2
-Unhandled exception: type error: illegal argument type for built-in operation
Stack backtrace (innermost last):
File "<stdin>", line 1
+TypeError: illegal argument type for built-in operation
>>>
\end{verbatim}\ecode
%
-The first line of the error message indicates what happened.
+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
-{\tt run-time error},
-{\tt undefined name}
+{\tt ZeroDivisionError},
+{\tt NameError}
and
-{\tt type error}.
-The rest of the line is a detail whose interpretation depends on the
-exception type.
+{\tt 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
+exceptions, but need not be true for user-defined exceptions (although
+it is a useful convention).
+Standard exception names are built-in identifiers (not reserved
+keywords).
-The rest of the error message shows the context where the
-exception happened.
+The rest of the line is a detail whose interpretation depends on the
+exception type; its meaning is dependent on the exception type.
+
+The preceding part of the error message shows the context where the
+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.
-Here is a summary of the most common exceptions:
-\begin{itemize}
-\item
-{\em Run-time\ errors}
-are generally caused by wrong data used by the program; this can be the
-programmer's fault or caused by bad input.
-The detail states the cause of the error in more detail.
-\item
-{\em Undefined\ name}
-errors are more serious: these are usually caused by misspelled
-identifiers.%
-\footnote{
- The parser does not check whether names used in a program are at
- all defined elsewhere in the program; such checks are
- postponed until run-time. The same holds for type checking.
-}
-The detail is the offending identifier.
-\item
-{\em Type\ errors} are also pretty serious: this is another case of
-using wrong data (or better, using data the wrong way), but here the
-error can be gleaned from the object type(s) alone. The detail shows
-in what context the error was detected.
-\end{itemize}
+The Python library reference manual lists the built-in exceptions and
+their meanings.
\section{Handling Exceptions}
@@ -1813,7 +1805,7 @@
... print x,
... try:
... print 1.0 / x
-... except RuntimeError:
+... except ZeroDivisionError:
... print '*** has no inverse ***'
...
0.3333 3.00030003
@@ -1862,7 +1854,8 @@
%
The last except clause may omit the exception name(s), to serve as a
wildcard.
-Use this with extreme caution!
+Use this with extreme caution, since it is easy to mask a real
+programming error in this way!
When an exception occurs, it may have an associated value, also known as
the exceptions's
@@ -1882,31 +1875,9 @@
>>>
\end{verbatim}\ecode
%
-If an exception has an argument, it is printed as the third part
+If an exception has an argument, it is printed as the last part
(`detail') of the message for unhandled exceptions.
-Standard exception names are built-in identifiers (not reserved
-keywords).
-These are in fact string objects whose
-{\em object\ identity}
-(not their value!) identifies the exceptions.
-The string is printed as the second part of the message for unhandled
-exceptions.
-Their names and values are:
-
-\bcode\begin{verbatim}
-EOFError 'end-of-file read'
-KeyboardInterrupt 'keyboard interrupt'
-MemoryError 'out of memory' *
-NameError 'undefined name' *
-RuntimeError 'run-time error' *
-SystemError 'system error' *
-TypeError 'type error' *
-\end{verbatim}\ecode
-%
-The meanings should be clear enough.
-Those exceptions with a {\tt *} in the third column have an argument.
-
Exception handlers don't just handle exceptions if they occur
immediately in the try clause, but also if they occur inside functions
that are called (even indirectly) in the try clause.
@@ -1918,10 +1889,10 @@
...
>>> try:
... this_fails()
-... except RuntimeError, detail:
+... except ZeroDivisionError, detail:
... print 'Handling run-time error:', detail
...
-Handling run-time error: integer division by zero
+Handling run-time error: integer division or modulo
>>>
\end{verbatim}\ecode
@@ -1932,10 +1903,10 @@
For example:
\bcode\begin{verbatim}
->>> raise NameError, 'Hi There!'
-Unhandled exception: undefined name: Hi There!
+>>> raise NameError, 'HiThere'
Stack backtrace (innermost last):
File "<stdin>", line 1
+NameError: HiThere
>>>
\end{verbatim}\ecode
%
@@ -1949,7 +1920,7 @@
For example:
\bcode\begin{verbatim}
->>> my_exc = 'Nobody likes me'
+>>> my_exc = 'my_exc'
>>> try:
... raise my_exc, 2*2
... except my_exc, val:
@@ -1957,9 +1928,9 @@
...
My exception occured, value: 4
>>> raise my_exc, 1
-Nobody likes me: 1
Stack backtrace (innermost last):
File "<stdin>", line 7
+my_exc: 1
>>>
\end{verbatim}\ecode
%
@@ -1979,9 +1950,9 @@
... print 'Goodbye, world!'
...
Goodbye, world!
-Unhandled exception: keyboard interrupt
Stack backtrace (innermost last):
File "<stdin>", line 2
+KeyboardInterrupt
>>>
\end{verbatim}\ecode
%