451 lines
18 KiB
TeX
451 lines
18 KiB
TeX
\section{Built-in Exceptions}
|
|
|
|
\declaremodule{standard}{exceptions}
|
|
\modulesynopsis{Standard exception classes.}
|
|
|
|
|
|
Exceptions should be class objects.
|
|
The exceptions are defined in the module \module{exceptions}. This
|
|
module never needs to be imported explicitly: the exceptions are
|
|
provided in the built-in namespace as well as the \module{exceptions}
|
|
module.
|
|
|
|
For class exceptions, in a \keyword{try}\stindex{try} statement with
|
|
an \keyword{except}\stindex{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.
|
|
|
|
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
|
|
\keyword{raise}\stindex{raise} statement. For string exceptions, the
|
|
associated value itself will be stored in the variable named as the
|
|
second argument of the \keyword{except} clause (if any). For class
|
|
exceptions, that variable receives the exception instance. If the
|
|
exception class is derived from the standard root class
|
|
\exception{BaseException}, the associated value is present as the
|
|
exception instance's \member{args} attribute. If there is a single argument
|
|
(as is preferred), it is bound to the \member{message} attribute.
|
|
|
|
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
|
|
situation in which the interpreter raises the same exception; but
|
|
beware that there is nothing to prevent user code from raising an
|
|
inappropriate error.
|
|
|
|
The built-in exception classes can be sub-classed to define new
|
|
exceptions; programmers are encouraged to at least derive new
|
|
exceptions from the \exception{Exception} class and not
|
|
\exception{BaseException}. More
|
|
information on defining exceptions is available in the
|
|
\citetitle[../tut/tut.html]{Python Tutorial} under the heading
|
|
``User-defined Exceptions.''
|
|
|
|
\setindexsubitem{(built-in exception base class)}
|
|
|
|
The following exceptions are only used as base classes for other
|
|
exceptions.
|
|
|
|
\begin{excdesc}{BaseException}
|
|
The base class for all built-in exceptions. It is not meant to be directly
|
|
inherited by user-defined classes (for that use \exception{Exception}). If
|
|
\function{str()} or \function{unicode()} is called on an instance of this
|
|
class, the representation of the argument(s) to the instance are returned or
|
|
the emptry string when there were no arguments. If only a single argument is
|
|
passed in, it is stored in the \member{message} attribute. If more than one
|
|
argument is passed in, \member{message} is set to the empty string. These
|
|
semantics are meant to reflect the fact that \member{message} is to store a
|
|
text message explaining why the exception had been raised. If more data needs
|
|
to be attached to the exception, attach it through arbitrary attributes on the
|
|
instance. All arguments are also stored in \member{args} as a tuple, but it will
|
|
eventually be deprecated and thus its use is discouraged.
|
|
\versionadded{2.5}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{Exception}
|
|
All built-in, non-system-exiting exceptions are derived
|
|
from this class. All user-defined exceptions should also be derived
|
|
from this class.
|
|
\versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{StandardError}
|
|
The base class for all built-in exceptions except
|
|
\exception{StopIteration}, \exception{GeneratorExit},
|
|
\exception{KeyboardInterrupt} and \exception{SystemExit}.
|
|
\exception{StandardError} itself is derived from \exception{Exception}.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{ArithmeticError}
|
|
The base class for those built-in exceptions that are raised for
|
|
various arithmetic errors: \exception{OverflowError},
|
|
\exception{ZeroDivisionError}, \exception{FloatingPointError}.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{LookupError}
|
|
The base class for the exceptions that are raised when a key or
|
|
index used on a mapping or sequence is invalid: \exception{IndexError},
|
|
\exception{KeyError}. This can be raised directly by
|
|
\function{sys.setdefaultencoding()}.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{EnvironmentError}
|
|
The base class for exceptions that
|
|
can occur outside the Python system: \exception{IOError},
|
|
\exception{OSError}. When exceptions of this type are created with a
|
|
2-tuple, the first item is available on the instance's \member{errno}
|
|
attribute (it is assumed to be an error number), and the second item
|
|
is available on the \member{strerror} attribute (it is usually the
|
|
associated error message). The tuple itself is also available on the
|
|
\member{args} attribute.
|
|
\versionadded{1.5.2}
|
|
|
|
When an \exception{EnvironmentError} exception is instantiated with a
|
|
3-tuple, the first two items are available as above, while the third
|
|
item is available on the \member{filename} attribute. However, for
|
|
backwards compatibility, the \member{args} attribute contains only a
|
|
2-tuple of the first two constructor arguments.
|
|
|
|
The \member{filename} attribute is \code{None} when this exception is
|
|
created with other than 3 arguments. The \member{errno} and
|
|
\member{strerror} attributes are also \code{None} when the instance was
|
|
created with other than 2 or 3 arguments. In this last case,
|
|
\member{args} contains the verbatim constructor arguments as a tuple.
|
|
\end{excdesc}
|
|
|
|
|
|
\setindexsubitem{(built-in exception)}
|
|
|
|
The following exceptions are the exceptions that are actually raised.
|
|
|
|
\begin{excdesc}{AssertionError}
|
|
\stindex{assert}
|
|
Raised when an \keyword{assert} statement fails.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{AttributeError}
|
|
% xref to attribute reference?
|
|
Raised when an attribute reference or assignment fails. (When an
|
|
object does not support attribute references or attribute assignments
|
|
at all, \exception{TypeError} is raised.)
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{EOFError}
|
|
% XXXJH xrefs here
|
|
Raised when one of the built-in functions (\function{input()} or
|
|
\function{raw_input()}) hits an end-of-file condition (\EOF) without
|
|
reading any data.
|
|
% XXXJH xrefs here
|
|
(N.B.: the \method{read()} and \method{readline()} methods of file
|
|
objects return an empty string when they hit \EOF.)
|
|
\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 \longprogramopt{with-fpectl} option, or the
|
|
\constant{WANT_SIGFPE_HANDLER} symbol is defined in the
|
|
\file{pyconfig.h} file.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{GeneratorExit}
|
|
Raise when a generator's \method{close()} method is called.
|
|
It directly inherits from \exception{Exception} instead of
|
|
\exception{StandardError} since it is technically not an error.
|
|
\versionadded{2.5}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{IOError}
|
|
% XXXJH xrefs here
|
|
Raised when an I/O operation (such as a \keyword{print} statement,
|
|
the built-in \function{open()} function or a method of a file
|
|
object) fails for an I/O-related reason, e.g., ``file not found'' or
|
|
``disk full''.
|
|
|
|
This class is derived from \exception{EnvironmentError}. See the
|
|
discussion above for more information on exception instance
|
|
attributes.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{ImportError}
|
|
% XXXJH xref to import statement?
|
|
Raised when an \keyword{import} statement fails to find the module
|
|
definition or when a \code{from \textrm{\ldots} import} fails to find a
|
|
name that is to be imported.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{IndexError}
|
|
% XXXJH xref to sequences
|
|
Raised when a sequence subscript is out of range. (Slice indices are
|
|
silently truncated to fall in the allowed range; if an index is not a
|
|
plain integer, \exception{TypeError} is raised.)
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{KeyError}
|
|
% XXXJH xref to mapping objects?
|
|
Raised when a mapping (dictionary) key is not found in the set of
|
|
existing keys.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{KeyboardInterrupt}
|
|
Raised when the user hits the interrupt key (normally
|
|
\kbd{Control-C} or \kbd{Delete}). During execution, a check for
|
|
interrupts is made regularly.
|
|
% XXX(hylton) xrefs here
|
|
Interrupts typed when a built-in function \function{input()} or
|
|
\function{raw_input()} is waiting for input also raise this
|
|
exception.
|
|
The exception inherits from \exception{BaseException} so as to not be
|
|
accidentally caught by code that catches \exception{Exception} and thus
|
|
prevent the interpreter from exiting.
|
|
\versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{MemoryError}
|
|
Raised when an operation runs out of memory but the situation may
|
|
still be rescued (by deleting some objects). The associated value is
|
|
a string indicating what kind of (internal) operation ran out of memory.
|
|
Note that because of the underlying memory management architecture
|
|
(C's \cfunction{malloc()} function), the interpreter may not
|
|
always be able to completely recover from this situation; it
|
|
nevertheless raises an exception so that a stack traceback can be
|
|
printed, in case a run-away program was the cause.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{NameError}
|
|
Raised when a local or global name is not found. This applies only
|
|
to unqualified names. The associated value is an error message that
|
|
includes the name that could not be found.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{NotImplementedError}
|
|
This exception is derived from \exception{RuntimeError}. In user
|
|
defined base classes, abstract methods should raise this exception
|
|
when they require derived classes to override the method.
|
|
\versionadded{1.5.2}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{OSError}
|
|
%xref for os module
|
|
This class is derived from \exception{EnvironmentError} and is used
|
|
primarily as the \refmodule{os} module's \code{os.error} exception.
|
|
See \exception{EnvironmentError} above for a description of the
|
|
possible associated values.
|
|
\versionadded{1.5.2}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{OverflowError}
|
|
% XXXJH reference to long's and/or int's?
|
|
Raised when the result of an arithmetic operation is too large to be
|
|
represented. This cannot occur for long integers (which would rather
|
|
raise \exception{MemoryError} than give up). Because of the lack of
|
|
standardization of floating point exception handling in C, most
|
|
floating point operations also aren't checked. For plain integers,
|
|
all operations that can overflow are checked except left shift, where
|
|
typical applications prefer to drop bits than raise an exception.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{ReferenceError}
|
|
This exception is raised when a weak reference proxy, created by the
|
|
\function{\refmodule{weakref}.proxy()} function, is used to access
|
|
an attribute of the referent after it has been garbage collected.
|
|
For more information on weak references, see the \refmodule{weakref}
|
|
module.
|
|
\versionadded[Previously known as the
|
|
\exception{\refmodule{weakref}.ReferenceError}
|
|
exception]{2.2}
|
|
\end{excdesc}
|
|
|
|
\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 mostly a relic from a
|
|
previous version of the interpreter; it is not used very much any
|
|
more.)
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{StopIteration}
|
|
Raised by an iterator's \method{next()} method to signal that there
|
|
are no further values.
|
|
This is derived from \exception{Exception} rather than
|
|
\exception{StandardError}, since this is not considered an error in
|
|
its normal application.
|
|
\versionadded{2.2}
|
|
\end{excdesc}
|
|
|
|
|
|
\begin{excdesc}{SyntaxError}
|
|
% XXXJH xref to these functions?
|
|
Raised when the parser encounters a syntax error. This may occur in
|
|
an \keyword{import} statement, in an \keyword{exec} statement, in a call
|
|
to the built-in function \function{eval()} or \function{input()}, or
|
|
when reading the initial script or standard input (also
|
|
interactively).
|
|
|
|
Instances of this class have attributes \member{filename},
|
|
\member{lineno}, \member{offset} and \member{text} for easier access
|
|
to the details. \function{str()} of the exception instance returns
|
|
only the message.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{SystemError}
|
|
Raised when the interpreter finds an internal error, but the
|
|
situation does not look so serious to cause it to abandon all hope.
|
|
The associated value is a string indicating what went wrong (in
|
|
low-level terms).
|
|
|
|
You should report this to the author or maintainer of your Python
|
|
interpreter. Be sure to report the version of the Python
|
|
interpreter (\code{sys.version}; it is also printed at the start of an
|
|
interactive Python session), the exact error message (the exception's
|
|
associated value) and if possible the source of the program that
|
|
triggered the error.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{SystemExit}
|
|
% XXX(hylton) xref to module sys?
|
|
This exception is raised by the \function{sys.exit()} function. When it
|
|
is not handled, the Python interpreter exits; no stack traceback is
|
|
printed. If the associated value is a plain integer, it specifies the
|
|
system exit status (passed to C's \cfunction{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.
|
|
|
|
Instances have an attribute \member{code} which is set to the
|
|
proposed exit status or error message (defaulting to \code{None}).
|
|
Also, this exception derives directly from \exception{BaseException} and
|
|
not \exception{StandardError}, since it is not technically an error.
|
|
|
|
A call to \function{sys.exit()} is translated into an exception so that
|
|
clean-up handlers (\keyword{finally} clauses of \keyword{try} statements)
|
|
can be executed, and so that a debugger can execute a script without
|
|
running the risk of losing control. The \function{os._exit()} function
|
|
can be used if it is absolutely positively necessary to exit
|
|
immediately (for example, in the child process after a call to
|
|
\function{fork()}).
|
|
|
|
The exception inherits from \exception{BaseException} instead of
|
|
\exception{StandardError} or \exception{Exception} so that it is not
|
|
accidentally caught by code that catches \exception{Exception}. This allows
|
|
the exception to properly propagate up and cause the interpreter to exit.
|
|
\versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{TypeError}
|
|
Raised when an operation or function is applied to an object
|
|
of inappropriate type. The associated value is a string giving
|
|
details about the type mismatch.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{UnboundLocalError}
|
|
Raised when a reference is made to a local variable in a function or
|
|
method, but no value has been bound to that variable. This is a
|
|
subclass of \exception{NameError}.
|
|
\versionadded{2.0}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{UnicodeError}
|
|
Raised when a Unicode-related encoding or decoding error occurs. It
|
|
is a subclass of \exception{ValueError}.
|
|
\versionadded{2.0}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{UnicodeEncodeError}
|
|
Raised when a Unicode-related error occurs during encoding. It
|
|
is a subclass of \exception{UnicodeError}.
|
|
\versionadded{2.3}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{UnicodeDecodeError}
|
|
Raised when a Unicode-related error occurs during decoding. It
|
|
is a subclass of \exception{UnicodeError}.
|
|
\versionadded{2.3}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{UnicodeTranslateError}
|
|
Raised when a Unicode-related error occurs during translating. It
|
|
is a subclass of \exception{UnicodeError}.
|
|
\versionadded{2.3}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{ValueError}
|
|
Raised when a built-in operation or function receives an argument
|
|
that has the right type but an inappropriate value, and the
|
|
situation is not described by a more precise exception such as
|
|
\exception{IndexError}.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{WindowsError}
|
|
Raised when a Windows-specific error occurs or when the error number
|
|
does not correspond to an \cdata{errno} value. The
|
|
\member{winerror} and \member{strerror} values are created from the
|
|
return values of the \cfunction{GetLastError()} and
|
|
\cfunction{FormatMessage()} functions from the Windows Platform API.
|
|
The \member{errno} value maps the \member{winerror} value to
|
|
corresponding \code{errno.h} values.
|
|
This is a subclass of \exception{OSError}.
|
|
\versionadded{2.0}
|
|
\versionchanged[Previous versions put the \cfunction{GetLastError()}
|
|
codes into \member{errno}]{2.5}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{ZeroDivisionError}
|
|
Raised when the second argument of a division or modulo operation is
|
|
zero. The associated value is a string indicating the type of the
|
|
operands and the operation.
|
|
\end{excdesc}
|
|
|
|
|
|
\setindexsubitem{(built-in warning)}
|
|
|
|
The following exceptions are used as warning categories; see the
|
|
\refmodule{warnings} module for more information.
|
|
|
|
\begin{excdesc}{Warning}
|
|
Base class for warning categories.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{UserWarning}
|
|
Base class for warnings generated by user code.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{DeprecationWarning}
|
|
Base class for warnings about deprecated features.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{PendingDeprecationWarning}
|
|
Base class for warnings about features which will be deprecated in the future.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{SyntaxWarning}
|
|
Base class for warnings about dubious syntax
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{RuntimeWarning}
|
|
Base class for warnings about dubious runtime behavior.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{FutureWarning}
|
|
Base class for warnings about constructs that will change semantically
|
|
in the future.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{ImportWarning}
|
|
Base class for warnings about probable mistakes in module imports.
|
|
\versionadded{2.5}
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{UnicodeWarning}
|
|
Base class for warnings related to Unicode.
|
|
\versionadded{2.5}
|
|
\end{excdesc}
|
|
|
|
The class hierarchy for built-in exceptions is:
|
|
|
|
\verbatiminput{../../Lib/test/exception_hierarchy.txt}
|