| \section{Built-in Exceptions} |
| |
| \declaremodule{standard}{exceptions} |
| \modulesynopsis{Standard exceptions classes.} |
| |
| |
| Exceptions can be class objects or string objects. Though most |
| exceptions have been string objects in past versions of Python, in |
| Python 1.5 and newer versions, all standard exceptions have been |
| converted to class objects, and users are encouraged to do the same. |
| 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. |
| |
| 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 \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{Exception}, the associated value is present as the |
| exception instance's \member{args} attribute, and possibly on other |
| attributes as well. |
| |
| 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} base class. 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}{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 \function{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. When used |
| as a sequence, this accesses the arguments given to the constructor |
| (handy for backward compatibility with old code). The arguments are |
| also available on the instance's \member{args} attribute, as a tuple. |
| \end{excdesc} |
| |
| \begin{excdesc}{StandardError} |
| The base class for all built-in exceptions except |
| \exception{StopIteration} and \exception{SystemExit}. |
| \exception{StandardError} itself is derived from the root class |
| \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}{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. |
| % XXXJH xrefs here |
| Interrupts typed when a built-in function \function{input()} or |
| \function{raw_input()}) is waiting for input also raise this |
| exception. |
| \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 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 atttributes \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} |
| % XXXJH 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{Exception} 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()}). |
| \end{excdesc} |
| |
| \begin{excdesc}{TypeError} |
| Raised when a built-in 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}{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{errno} and \member{strerror} values are created from the |
| return values of the \cfunction{GetLastError()} and |
| \cfunction{FormatMessage()} functions from the Windows Platform API. |
| This is a subclass of \exception{OSError}. |
| \versionadded{2.0} |
| \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 |
| \module{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}{SyntaxWarning} |
| Base class for warnings about dubious syntax |
| \end{excdesc} |
| |
| \begin{excdesc}{RuntimeWarning} |
| Base class for warnings about dubious runtime behavior. |
| \end{excdesc} |
| |
| The full Exception class hierarchy is: |
| |
| \begin{verbatim} |
| Exception |
| +-- SystemExit |
| +-- StopIteration |
| +-- StandardError |
| | +-- KeyboardInterrupt |
| | +-- ImportError |
| | +-- EnvironmentError |
| | | +-- IOError |
| | | +-- OSError |
| | | +-- WindowsError |
| | +-- EOFError |
| | +-- RuntimeError |
| | | +-- NotImplementedError |
| | +-- NameError |
| | | +-- UnboundLocalError |
| | +-- AttributeError |
| | +-- SyntaxError |
| | | +-- IndentationError |
| | | +-- TabError |
| | +-- TypeError |
| | +-- AssertionError |
| | +-- LookupError |
| | | +-- IndexError |
| | | +-- KeyError |
| | +-- ArithmeticError |
| | | +-- OverflowError |
| | | +-- ZeroDivisionError |
| | | +-- FloatingPointError |
| | +-- ValueError |
| | | +-- UnicodeError |
| | +-- ReferenceError |
| | +-- SystemError |
| | +-- MemoryError |
| +---Warning |
| +-- UserWarning |
| +-- DeprecationWarning |
| +-- SyntaxWarning |
| +-- OverflowWarning |
| +-- RuntimeWarning |
| \end{verbatim} |