Documented new exceptions and exception classes.
This commit is contained in:
Guido van Rossum
parent
5344d4fd2e
commit
df3dba049d
|
|
@ -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.
|
||||
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.
|
||||
|
||||
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).
|
||||
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}
|
||||
|
|
|
|||
135
Doc/libexcs.tex
135
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.
|
||||
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.
|
||||
|
||||
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).
|
||||
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}
|
||||
|
|
|
|||
Loading…
Reference in New Issue