Documented new exceptions and exception classes.

2 files changed, 234 insertions, 40 deletions

diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex
index 7cc9195..e5dba34 100644
--- a/Doc/lib/libexcs.tex
+++ b/Doc/lib/libexcs.tex
@@ -1,25 +1,99 @@
 \section{Built-in Exceptions}
 
-Exceptions are string objects.  Two distinct string objects with the
-same value are different exceptions.  This is done to force programmers
-to use exception names rather than their string value when specifying
-exception handlers.  The string value of all built-in exceptions is
-their name, but this is not a requirement for user-defined exceptions
-or exceptions defined by library modules.
-
-The following exceptions can be generated by the interpreter or
-built-in functions.  Except where mentioned, they have an `associated
-value' indicating the detailed cause of the error.  This may be a
-string or a tuple containing several items of information (e.g., an
-error code and a string explaining the code).
+Exceptions can be class objects or string objects.  While
+traditionally, most exceptions have been string objects, in Python
+1.5a4, all standard exceptions have been converted to class objects,
+and users are encouraged to the the same.  The source code for those
+exceptions is present in the standard library module
+\code{exceptions}; this module never needs to be imported explicitly.
+
+For backward compatibility, when Python is invoked with the \code{-X}
+option, the standard exceptions are strings.  This may be needed to
+run some code that breaks because of the different semantics of class
+based exceptions.  The \code{-X} option will become obsolete in future
+Python versions, so the recommended solution is to fix the code.
+
+Two distinct string objects with the same value are considered different
+exceptions.  This is done to force programmers to use exception names
+rather than their string value when specifying exception handlers.
+The string value of all built-in exceptions is their name, but this is
+not a requirement for user-defined exceptions or exceptions defined by
+library modules.
+
+For class exceptions, in a \code{try} statement with an\code{except}
+clause that mentions a particular class, that clause also handles
+any exception classes derived from that class (but not exception
+classes from which \emph{it} is derived).  Two exception classes
+that are not related via subclassing are never equivalent, even if
+they have the same name.
+\stindex{try}
+\stindex{except}
+
+The built-in exceptions listed below can be generated by the
+interpreter or built-in functions.  Except where mentioned, they have
+an ``associated value'' indicating the detailed cause of the error.
+This may be a string or a tuple containing several items of
+information (e.g., an error code and a string explaining the code).
+The associated value is the second argument to the \code{raise}
+statement.  For string exceptions, the associated value itself will be
+stored in the variable named as the second argument of the
+\code{except} clause (if any).  For class exceptions derived from
+the root class \code{Exception}, that variable receives the exception
+instance, and the associated value is present as the exception
+instance's \code{args} attribute; this is a tuple even if the second
+argument to \code{raise} was not (then it is a singleton tuple).
+\stindex{raise}
 
 User code can raise built-in exceptions.  This can be used to test an
-exception handler or to report an error condition `just like' the
+exception handler or to report an error condition ``just like'' the
 situation in which the interpreter raises the same exception; but
 beware that there is nothing to prevent user code from raising an
 inappropriate error.
 
-\renewcommand{\indexsubitem}{(built-in exception)}
+\renewcommand{\indexsubitem}{(built-in exception base class)}
+
+The following exceptions are only used as base classes for other
+exceptions.  When string-based standard exceptions are used, they
+are tuples containing the directly derived classes.
+
+\begin{excdesc}{Exception}
+The root class for exceptions.  All built-in exceptions are derived
+from this class.  All user-defined exceptions should also be derived
+from this class, but this is not (yet) enforced.  The \code{str()}
+function, when applied to an instance of this class (or most derived
+classes) returns the string value of the argument or arguments, or an
+empty string if no arguments were given to the constructor.
+\end{excdesc}
+
+\begin{excdesc}{StandardError}
+The base class for built-in exceptions.  All built-in exceptions are
+derived from this class, which is itself derived from the root class
+\code{Exception}.  For backward compatibility, when used as a
+sequence, this accesses the arguments given to the constructor.
+\end{excdesc}
+
+\begin{excdesc}{ArithmeticError}
+The base class for those built-in exceptions that are raised for
+various arithmetic errors: \code{OverflowError},
+\code{ZeroDivisionError}, \code{FloatingPointError}.
+\end{excdesc}
+
+\begin{excdesc}{LookupError}
+The base class for thise exceptions that are raised when a key or
+index used on a mapping or sequence is invalid: \code{IndexError},
+\code{KeyError}.
+\end{excdesc}
+
+\renewcommand{\indexsubitem}{(built-in exception base class)}
+
+The following exceptions are the exceptions that are actually raised.
+They are class objects, except when the \code{-X} option is used to
+revert back to string-based standard exceptions.
+
+\begin{excdesc}{AssertionError}
+Raised when an \code{assert} statement fails.
+\stindex{assert}
+\end{excdesc}
 
 \begin{excdesc}{AttributeError}
 % xref to attribute reference?
@@ -38,11 +112,24 @@ inappropriate error.
   objects return an empty string when they hit \EOF{}.)  No associated value.
 \end{excdesc}
 
+\begin{excdesc}{FloatingPointError}
+Raised when a floating point operation fails.  This exception is
+always defined, but can only be raised when Python is configured with
+the \code{--with-fpectl} option, or the \code{WANT_SIGFPE_HANDLER}
+symbol is defined in the \file{config.h} file.
+\end{excdesc}
+
 \begin{excdesc}{IOError}
 % XXXJH xrefs here
   Raised when an I/O operation (such as a \code{print} statement, the
   built-in \code{open()} function or a method of a file object) fails
-  for an I/O-related reason, e.g., `file not found', `disk full'.
+  for an I/O-related reason, e.g., ``file not found'' or ``disk full''.
+
+When class exceptions are used, and this exception is instantiated as
+\code{IOError(errno, strerror)}, the instance has two additional
+attributes \code{errno} and \code{strerror} set to the error code and
+the error message, respectively.  These attributes default to
+\code{None}.
 \end{excdesc}
 
 \begin{excdesc}{ImportError}
@@ -106,10 +193,9 @@ inappropriate error.
 \begin{excdesc}{RuntimeError}
   Raised when an error is detected that doesn't fall in any of the
   other categories.  The associated value is a string indicating what
-  precisely went wrong.  (This exception is a relic from a previous
-  version of the interpreter; it is not used any more except by some
-  extension modules that haven't been converted to define their own
-  exceptions yet.)
+  precisely went wrong.  (This exception is mostly a relic from a
+  previous version of the interpreter; it is not used very much any
+  more.)
 \end{excdesc}
 
 \begin{excdesc}{SyntaxError}
@@ -119,6 +205,13 @@ inappropriate error.
   to the built-in function \code{eval()} or \code{input()}, or
   when reading the initial script or standard input (also
   interactively).
+
+When class exceptions are used, instances of this class have
+atttributes \code{filename}, \code{lineno}, \code{offset} and
+\code{text} for easier access to the details; for string exceptions,
+the associated value is usually a tuple of the form
+\code{(message, (filename, lineno, offset, text))}.
+For class exceptions, \code{str()} returns only the message.
 \end{excdesc}
 
 \begin{excdesc}{SystemError}
@@ -143,11 +236,15 @@ inappropriate error.
   system exit status (passed to \C{}'s \code{exit()} function); if it is
   \code{None}, the exit status is zero; if it has another type (such as
   a string), the object's value is printed and the exit status is one.
+
+When class exceptions are used, the instance has an attribute
+\code{code} which is set to the proposed exit status or error message
+(defaulting to \code{None}).
   
   A call to \code{sys.exit} is translated into an exception so that
   clean-up handlers (\code{finally} clauses of \code{try} statements)
   can be executed, and so that a debugger can execute a script without
-  running the risk of losing control.  The \code{posix._exit()} function
+  running the risk of losing control.  The \code{os._exit()} function
   can be used if it is absolutely positively necessary to exit
   immediately (e.g., after a \code{fork()} in the child process).
 \end{excdesc}
diff --git a/Doc/libexcs.tex b/Doc/libexcs.tex
index 7cc9195..e5dba34 100644
--- a/Doc/libexcs.tex
+++ b/Doc/libexcs.tex
@@ -1,25 +1,99 @@
 \section{Built-in Exceptions}
 
-Exceptions are string objects.  Two distinct string objects with the
-same value are different exceptions.  This is done to force programmers
-to use exception names rather than their string value when specifying
-exception handlers.  The string value of all built-in exceptions is
-their name, but this is not a requirement for user-defined exceptions
-or exceptions defined by library modules.
-
-The following exceptions can be generated by the interpreter or
-built-in functions.  Except where mentioned, they have an `associated
-value' indicating the detailed cause of the error.  This may be a
-string or a tuple containing several items of information (e.g., an
-error code and a string explaining the code).
+Exceptions can be class objects or string objects.  While
+traditionally, most exceptions have been string objects, in Python
+1.5a4, all standard exceptions have been converted to class objects,
+and users are encouraged to the the same.  The source code for those
+exceptions is present in the standard library module
+\code{exceptions}; this module never needs to be imported explicitly.
+
+For backward compatibility, when Python is invoked with the \code{-X}
+option, the standard exceptions are strings.  This may be needed to
+run some code that breaks because of the different semantics of class
+based exceptions.  The \code{-X} option will become obsolete in future
+Python versions, so the recommended solution is to fix the code.
+
+Two distinct string objects with the same value are considered different
+exceptions.  This is done to force programmers to use exception names
+rather than their string value when specifying exception handlers.
+The string value of all built-in exceptions is their name, but this is
+not a requirement for user-defined exceptions or exceptions defined by
+library modules.
+
+For class exceptions, in a \code{try} statement with an\code{except}
+clause that mentions a particular class, that clause also handles
+any exception classes derived from that class (but not exception
+classes from which \emph{it} is derived).  Two exception classes
+that are not related via subclassing are never equivalent, even if
+they have the same name.
+\stindex{try}
+\stindex{except}
+
+The built-in exceptions listed below can be generated by the
+interpreter or built-in functions.  Except where mentioned, they have
+an ``associated value'' indicating the detailed cause of the error.
+This may be a string or a tuple containing several items of
+information (e.g., an error code and a string explaining the code).
+The associated value is the second argument to the \code{raise}
+statement.  For string exceptions, the associated value itself will be
+stored in the variable named as the second argument of the
+\code{except} clause (if any).  For class exceptions derived from
+the root class \code{Exception}, that variable receives the exception
+instance, and the associated value is present as the exception
+instance's \code{args} attribute; this is a tuple even if the second
+argument to \code{raise} was not (then it is a singleton tuple).
+\stindex{raise}
 
 User code can raise built-in exceptions.  This can be used to test an
-exception handler or to report an error condition `just like' the
+exception handler or to report an error condition ``just like'' the
 situation in which the interpreter raises the same exception; but
 beware that there is nothing to prevent user code from raising an
 inappropriate error.
 
-\renewcommand{\indexsubitem}{(built-in exception)}
+\renewcommand{\indexsubitem}{(built-in exception base class)}
+
+The following exceptions are only used as base classes for other
+exceptions.  When string-based standard exceptions are used, they
+are tuples containing the directly derived classes.
+
+\begin{excdesc}{Exception}
+The root class for exceptions.  All built-in exceptions are derived
+from this class.  All user-defined exceptions should also be derived
+from this class, but this is not (yet) enforced.  The \code{str()}
+function, when applied to an instance of this class (or most derived
+classes) returns the string value of the argument or arguments, or an
+empty string if no arguments were given to the constructor.
+\end{excdesc}
+
+\begin{excdesc}{StandardError}
+The base class for built-in exceptions.  All built-in exceptions are
+derived from this class, which is itself derived from the root class
+\code{Exception}.  For backward compatibility, when used as a
+sequence, this accesses the arguments given to the constructor.
+\end{excdesc}
+
+\begin{excdesc}{ArithmeticError}
+The base class for those built-in exceptions that are raised for
+various arithmetic errors: \code{OverflowError},
+\code{ZeroDivisionError}, \code{FloatingPointError}.
+\end{excdesc}
+
+\begin{excdesc}{LookupError}
+The base class for thise exceptions that are raised when a key or
+index used on a mapping or sequence is invalid: \code{IndexError},
+\code{KeyError}.
+\end{excdesc}
+
+\renewcommand{\indexsubitem}{(built-in exception base class)}
+
+The following exceptions are the exceptions that are actually raised.
+They are class objects, except when the \code{-X} option is used to
+revert back to string-based standard exceptions.
+
+\begin{excdesc}{AssertionError}
+Raised when an \code{assert} statement fails.
+\stindex{assert}
+\end{excdesc}
 
 \begin{excdesc}{AttributeError}
 % xref to attribute reference?
@@ -38,11 +112,24 @@ inappropriate error.
   objects return an empty string when they hit \EOF{}.)  No associated value.
 \end{excdesc}
 
+\begin{excdesc}{FloatingPointError}
+Raised when a floating point operation fails.  This exception is
+always defined, but can only be raised when Python is configured with
+the \code{--with-fpectl} option, or the \code{WANT_SIGFPE_HANDLER}
+symbol is defined in the \file{config.h} file.
+\end{excdesc}
+
 \begin{excdesc}{IOError}
 % XXXJH xrefs here
   Raised when an I/O operation (such as a \code{print} statement, the
   built-in \code{open()} function or a method of a file object) fails
-  for an I/O-related reason, e.g., `file not found', `disk full'.
+  for an I/O-related reason, e.g., ``file not found'' or ``disk full''.
+
+When class exceptions are used, and this exception is instantiated as
+\code{IOError(errno, strerror)}, the instance has two additional
+attributes \code{errno} and \code{strerror} set to the error code and
+the error message, respectively.  These attributes default to
+\code{None}.
 \end{excdesc}
 
 \begin{excdesc}{ImportError}
@@ -106,10 +193,9 @@ inappropriate error.
 \begin{excdesc}{RuntimeError}
   Raised when an error is detected that doesn't fall in any of the
   other categories.  The associated value is a string indicating what
-  precisely went wrong.  (This exception is a relic from a previous
-  version of the interpreter; it is not used any more except by some
-  extension modules that haven't been converted to define their own
-  exceptions yet.)
+  precisely went wrong.  (This exception is mostly a relic from a
+  previous version of the interpreter; it is not used very much any
+  more.)
 \end{excdesc}
 
 \begin{excdesc}{SyntaxError}
@@ -119,6 +205,13 @@ inappropriate error.
   to the built-in function \code{eval()} or \code{input()}, or
   when reading the initial script or standard input (also
   interactively).
+
+When class exceptions are used, instances of this class have
+atttributes \code{filename}, \code{lineno}, \code{offset} and
+\code{text} for easier access to the details; for string exceptions,
+the associated value is usually a tuple of the form
+\code{(message, (filename, lineno, offset, text))}.
+For class exceptions, \code{str()} returns only the message.
 \end{excdesc}
 
 \begin{excdesc}{SystemError}
@@ -143,11 +236,15 @@ inappropriate error.
   system exit status (passed to \C{}'s \code{exit()} function); if it is
   \code{None}, the exit status is zero; if it has another type (such as
   a string), the object's value is printed and the exit status is one.
+
+When class exceptions are used, the instance has an attribute
+\code{code} which is set to the proposed exit status or error message
+(defaulting to \code{None}).
   
   A call to \code{sys.exit} is translated into an exception so that
   clean-up handlers (\code{finally} clauses of \code{try} statements)
   can be executed, and so that a debugger can execute a script without
-  running the risk of losing control.  The \code{posix._exit()} function
+  running the risk of losing control.  The \code{os._exit()} function
   can be used if it is absolutely positively necessary to exit
   immediately (e.g., after a \code{fork()} in the child process).
 \end{excdesc}