\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?
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}
\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}
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}
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}
\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?
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}
\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}
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}
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}
projects / python / commitdiff