Lots of small changes collected over months...

Doc/Makefile

@@ -31,7 +31,7 @@ qua:
 	bibtex qua
 	latex qua
 	latex qua
-	dvips lib >qua.ps
+	dvips qua >qua.ps
 
 libinfo:
 	@echo This may take a while...

Doc/ref/ref3.tex

@@ -290,10 +290,17 @@ There is currently a single mapping type:
 \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 @@ base class list.
 \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 @@ interpretations are used in this case.
 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}
 

Doc/ref/ref5.tex

@@ -176,8 +176,9 @@ The key/datum pairs are evaluated from left to right to define the
 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 @@ corresponding items.
 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;

Doc/ref3.tex

@@ -290,10 +290,17 @@ There is currently a single mapping type:
 \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 @@ base class list.
 \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 @@ interpretations are used in this case.
 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}
 

Doc/ref5.tex

@@ -176,8 +176,9 @@ The key/datum pairs are evaluated from left to right to define the
 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 @@ corresponding items.
 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;

Doc/tut.tex

@@ -183,6 +183,12 @@ program will encounter EOF immediately.  In the former case (which is
 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 @@ and a copyright notice before printing the first prompt, e.g.:
 
 \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 @@ however, and result in error messages as shown here:
 
 \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}.
+{\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 line is a detail whose interpretation depends on the
-exception type.
+exception type; its meaning is dependent on the exception type.
 
-The rest of the error message shows the context where the
-exception happened.
+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 @@ some floating point numbers:
 ...     print x,
 ...     try:
 ...         print 1.0 / x
-...     except RuntimeError:
+...     except ZeroDivisionError:
 ...         print '*** has no inverse ***'
 ... 
 0.3333 3.00030003
@@ -1862,7 +1854,8 @@ e.g.:
 %
 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 @@ name foo undefined
 >>> 
 \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 @@ For example:
 ... 
 >>> 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 @@ exception to occur.
 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 @@ variable.
 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 @@ For example:
 ... 
 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 @@ For example:
 ...     print 'Goodbye, world!'
 ... 
 Goodbye, world!
-Unhandled exception: keyboard interrupt
 Stack backtrace (innermost last):
   File "<stdin>", line 2
+KeyboardInterrupt
 >>> 
 \end{verbatim}\ecode
 %

Doc/tut/tut.tex

@@ -183,6 +183,12 @@ program will encounter EOF immediately.  In the former case (which is
 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 @@ and a copyright notice before printing the first prompt, e.g.:
 
 \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 @@ however, and result in error messages as shown here:
 
 \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}.
+{\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 line is a detail whose interpretation depends on the
-exception type.
+exception type; its meaning is dependent on the exception type.
 
-The rest of the error message shows the context where the
-exception happened.
+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 @@ some floating point numbers:
 ...     print x,
 ...     try:
 ...         print 1.0 / x
-...     except RuntimeError:
+...     except ZeroDivisionError:
 ...         print '*** has no inverse ***'
 ... 
 0.3333 3.00030003
@@ -1862,7 +1854,8 @@ e.g.:
 %
 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 @@ name foo undefined
 >>> 
 \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 @@ For example:
 ... 
 >>> 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 @@ exception to occur.
 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 @@ variable.
 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 @@ For example:
 ... 
 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 @@ For example:
 ...     print 'Goodbye, world!'
 ... 
 Goodbye, world!
-Unhandled exception: keyboard interrupt
 Stack backtrace (innermost last):
   File "<stdin>", line 2
+KeyboardInterrupt
 >>> 
 \end{verbatim}\ecode
 %