Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1 | \section{Built-in Exceptions} |
Fred Drake | 3bd9ab0 | 1998-07-23 19:33:08 +0000 | [diff] [blame] | 2 | |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 3 | \declaremodule{standard}{exceptions} |
Andrew M. Kuchling | 032bd0a | 2003-05-13 14:13:58 +0000 | [diff] [blame] | 4 | \modulesynopsis{Standard exception classes.} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 5 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 6 | |
Neal Norwitz | 847207a | 2003-05-29 02:17:23 +0000 | [diff] [blame] | 7 | Exceptions should be class objects. |
Fred Drake | 7acb218 | 2000-09-09 03:28:00 +0000 | [diff] [blame] | 8 | The exceptions are defined in the module \module{exceptions}. This |
| 9 | module never needs to be imported explicitly: the exceptions are |
Fred Drake | c692055 | 2001-09-21 21:12:30 +0000 | [diff] [blame] | 10 | provided in the built-in namespace as well as the \module{exceptions} |
| 11 | module. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 12 | |
Neal Norwitz | 847207a | 2003-05-29 02:17:23 +0000 | [diff] [blame] | 13 | \begin{notice} |
| 14 | In past versions of Python string exceptions were supported. In |
| 15 | Python 1.5 and newer versions, all standard exceptions have been |
| 16 | converted to class objects and users are encouraged to do the same. |
| 17 | String exceptions will raise a \code{PendingDeprecationWarning}. |
| 18 | In future versions, support for string exceptions will be removed. |
| 19 | |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 20 | Two distinct string objects with the same value are considered different |
| 21 | exceptions. This is done to force programmers to use exception names |
| 22 | rather than their string value when specifying exception handlers. |
| 23 | The string value of all built-in exceptions is their name, but this is |
| 24 | not a requirement for user-defined exceptions or exceptions defined by |
| 25 | library modules. |
Neal Norwitz | 847207a | 2003-05-29 02:17:23 +0000 | [diff] [blame] | 26 | \end{notice} |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 27 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 28 | For class exceptions, in a \keyword{try}\stindex{try} statement with |
| 29 | an \keyword{except}\stindex{except} clause that mentions a particular |
| 30 | class, that clause also handles any exception classes derived from |
| 31 | that class (but not exception classes from which \emph{it} is |
| 32 | derived). Two exception classes that are not related via subclassing |
| 33 | are never equivalent, even if they have the same name. |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 34 | |
| 35 | The built-in exceptions listed below can be generated by the |
| 36 | interpreter or built-in functions. Except where mentioned, they have |
| 37 | an ``associated value'' indicating the detailed cause of the error. |
| 38 | This may be a string or a tuple containing several items of |
| 39 | information (e.g., an error code and a string explaining the code). |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 40 | The associated value is the second argument to the |
| 41 | \keyword{raise}\stindex{raise} statement. For string exceptions, the |
| 42 | associated value itself will be stored in the variable named as the |
| 43 | second argument of the \keyword{except} clause (if any). For class |
| 44 | exceptions, that variable receives the exception instance. If the |
| 45 | exception class is derived from the standard root class |
| 46 | \exception{Exception}, the associated value is present as the |
| 47 | exception instance's \member{args} attribute, and possibly on other |
| 48 | attributes as well. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 49 | |
| 50 | User code can raise built-in exceptions. This can be used to test an |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 51 | exception handler or to report an error condition ``just like'' the |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 52 | situation in which the interpreter raises the same exception; but |
| 53 | beware that there is nothing to prevent user code from raising an |
| 54 | inappropriate error. |
| 55 | |
Fred Drake | c692055 | 2001-09-21 21:12:30 +0000 | [diff] [blame] | 56 | The built-in exception classes can be sub-classed to define new |
| 57 | exceptions; programmers are encouraged to at least derive new |
| 58 | exceptions from the \exception{Exception} base class. More |
| 59 | information on defining exceptions is available in the |
| 60 | \citetitle[../tut/tut.html]{Python Tutorial} under the heading |
| 61 | ``User-defined Exceptions.'' |
| 62 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 63 | \setindexsubitem{(built-in exception base class)} |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 64 | |
| 65 | The following exceptions are only used as base classes for other |
Fred Drake | 5828ad6 | 2000-04-06 15:03:01 +0000 | [diff] [blame] | 66 | exceptions. |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 67 | |
| 68 | \begin{excdesc}{Exception} |
| 69 | The root class for exceptions. All built-in exceptions are derived |
| 70 | from this class. All user-defined exceptions should also be derived |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 71 | from this class, but this is not (yet) enforced. The \function{str()} |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 72 | function, when applied to an instance of this class (or most derived |
| 73 | classes) returns the string value of the argument or arguments, or an |
Guido van Rossum | 6cd7ecb | 1997-10-07 14:41:04 +0000 | [diff] [blame] | 74 | empty string if no arguments were given to the constructor. When used |
| 75 | as a sequence, this accesses the arguments given to the constructor |
Barry Warsaw | da00c87 | 1998-07-23 19:57:35 +0000 | [diff] [blame] | 76 | (handy for backward compatibility with old code). The arguments are |
Fred Drake | c457ca7 | 1998-07-23 20:31:53 +0000 | [diff] [blame] | 77 | also available on the instance's \member{args} attribute, as a tuple. |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 78 | \end{excdesc} |
| 79 | |
| 80 | \begin{excdesc}{StandardError} |
Barry Warsaw | f2b4554 | 1999-02-24 00:27:14 +0000 | [diff] [blame] | 81 | The base class for all built-in exceptions except |
Fred Drake | c046e97 | 2001-07-23 19:19:39 +0000 | [diff] [blame] | 82 | \exception{StopIteration} and \exception{SystemExit}. |
| 83 | \exception{StandardError} itself is derived from the root class |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 84 | \exception{Exception}. |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 85 | \end{excdesc} |
| 86 | |
| 87 | \begin{excdesc}{ArithmeticError} |
| 88 | The base class for those built-in exceptions that are raised for |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 89 | various arithmetic errors: \exception{OverflowError}, |
| 90 | \exception{ZeroDivisionError}, \exception{FloatingPointError}. |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 91 | \end{excdesc} |
| 92 | |
| 93 | \begin{excdesc}{LookupError} |
Barry Warsaw | da00c87 | 1998-07-23 19:57:35 +0000 | [diff] [blame] | 94 | The base class for the exceptions that are raised when a key or |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 95 | index used on a mapping or sequence is invalid: \exception{IndexError}, |
Fred Drake | 53143be | 2000-10-25 21:05:29 +0000 | [diff] [blame] | 96 | \exception{KeyError}. This can be raised directly by |
| 97 | \function{sys.setdefaultencoding()}. |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 98 | \end{excdesc} |
| 99 | |
Barry Warsaw | da00c87 | 1998-07-23 19:57:35 +0000 | [diff] [blame] | 100 | \begin{excdesc}{EnvironmentError} |
| 101 | The base class for exceptions that |
| 102 | can occur outside the Python system: \exception{IOError}, |
| 103 | \exception{OSError}. When exceptions of this type are created with a |
| 104 | 2-tuple, the first item is available on the instance's \member{errno} |
| 105 | attribute (it is assumed to be an error number), and the second item |
| 106 | is available on the \member{strerror} attribute (it is usually the |
| 107 | associated error message). The tuple itself is also available on the |
| 108 | \member{args} attribute. |
Fred Drake | d0bceee | 1999-02-02 18:00:40 +0000 | [diff] [blame] | 109 | \versionadded{1.5.2} |
Barry Warsaw | da00c87 | 1998-07-23 19:57:35 +0000 | [diff] [blame] | 110 | |
| 111 | When an \exception{EnvironmentError} exception is instantiated with a |
| 112 | 3-tuple, the first two items are available as above, while the third |
| 113 | item is available on the \member{filename} attribute. However, for |
| 114 | backwards compatibility, the \member{args} attribute contains only a |
| 115 | 2-tuple of the first two constructor arguments. |
| 116 | |
| 117 | The \member{filename} attribute is \code{None} when this exception is |
| 118 | created with other than 3 arguments. The \member{errno} and |
| 119 | \member{strerror} attributes are also \code{None} when the instance was |
| 120 | created with other than 2 or 3 arguments. In this last case, |
| 121 | \member{args} contains the verbatim constructor arguments as a tuple. |
| 122 | \end{excdesc} |
| 123 | |
Fred Drake | 88c023b | 2000-09-07 16:33:32 +0000 | [diff] [blame] | 124 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 125 | \setindexsubitem{(built-in exception)} |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 126 | |
| 127 | The following exceptions are the exceptions that are actually raised. |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 128 | |
| 129 | \begin{excdesc}{AssertionError} |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 130 | \stindex{assert} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 131 | Raised when an \keyword{assert} statement fails. |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 132 | \end{excdesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 133 | |
| 134 | \begin{excdesc}{AttributeError} |
| 135 | % xref to attribute reference? |
| 136 | Raised when an attribute reference or assignment fails. (When an |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 137 | object does not support attribute references or attribute assignments |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 138 | at all, \exception{TypeError} is raised.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 139 | \end{excdesc} |
| 140 | |
| 141 | \begin{excdesc}{EOFError} |
| 142 | % XXXJH xrefs here |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 143 | Raised when one of the built-in functions (\function{input()} or |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 144 | \function{raw_input()}) hits an end-of-file condition (\EOF) without |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 145 | reading any data. |
| 146 | % XXXJH xrefs here |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 147 | (N.B.: the \method{read()} and \method{readline()} methods of file |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 148 | objects return an empty string when they hit \EOF.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 149 | \end{excdesc} |
| 150 | |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 151 | \begin{excdesc}{FloatingPointError} |
Fred Drake | b44e753 | 1998-07-27 21:11:42 +0000 | [diff] [blame] | 152 | Raised when a floating point operation fails. This exception is |
| 153 | always defined, but can only be raised when Python is configured |
Fred Drake | ee775a1 | 2000-04-11 19:46:40 +0000 | [diff] [blame] | 154 | with the \longprogramopt{with-fpectl} option, or the |
Fred Drake | b44e753 | 1998-07-27 21:11:42 +0000 | [diff] [blame] | 155 | \constant{WANT_SIGFPE_HANDLER} symbol is defined in the |
Martin v. Löwis | 4f1cd8b | 2001-07-26 13:41:06 +0000 | [diff] [blame] | 156 | \file{pyconfig.h} file. |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 157 | \end{excdesc} |
| 158 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 159 | \begin{excdesc}{IOError} |
| 160 | % XXXJH xrefs here |
Fred Drake | b44e753 | 1998-07-27 21:11:42 +0000 | [diff] [blame] | 161 | Raised when an I/O operation (such as a \keyword{print} statement, |
| 162 | the built-in \function{open()} function or a method of a file |
| 163 | object) fails for an I/O-related reason, e.g., ``file not found'' or |
| 164 | ``disk full''. |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 165 | |
Fred Drake | 02e18b4 | 1999-01-05 21:42:18 +0000 | [diff] [blame] | 166 | This class is derived from \exception{EnvironmentError}. See the |
Fred Drake | b44e753 | 1998-07-27 21:11:42 +0000 | [diff] [blame] | 167 | discussion above for more information on exception instance |
| 168 | attributes. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 169 | \end{excdesc} |
| 170 | |
| 171 | \begin{excdesc}{ImportError} |
| 172 | % XXXJH xref to import statement? |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 173 | Raised when an \keyword{import} statement fails to find the module |
Fred Drake | f65e323 | 1998-11-25 20:55:03 +0000 | [diff] [blame] | 174 | definition or when a \code{from \textrm{\ldots} import} fails to find a |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 175 | name that is to be imported. |
| 176 | \end{excdesc} |
| 177 | |
| 178 | \begin{excdesc}{IndexError} |
| 179 | % XXXJH xref to sequences |
| 180 | Raised when a sequence subscript is out of range. (Slice indices are |
| 181 | silently truncated to fall in the allowed range; if an index is not a |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 182 | plain integer, \exception{TypeError} is raised.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 183 | \end{excdesc} |
| 184 | |
| 185 | \begin{excdesc}{KeyError} |
| 186 | % XXXJH xref to mapping objects? |
| 187 | Raised when a mapping (dictionary) key is not found in the set of |
| 188 | existing keys. |
| 189 | \end{excdesc} |
| 190 | |
| 191 | \begin{excdesc}{KeyboardInterrupt} |
| 192 | Raised when the user hits the interrupt key (normally |
Fred Drake | 682d5f3 | 2001-07-12 02:09:51 +0000 | [diff] [blame] | 193 | \kbd{Control-C} or \kbd{Delete}). During execution, a check for |
Fred Drake | 2a1cc3e | 1998-04-28 13:38:54 +0000 | [diff] [blame] | 194 | interrupts is made regularly. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 195 | % XXXJH xrefs here |
Fred Drake | 2a1cc3e | 1998-04-28 13:38:54 +0000 | [diff] [blame] | 196 | Interrupts typed when a built-in function \function{input()} or |
Raymond Hettinger | b4c1d9b | 2003-05-10 08:51:28 +0000 | [diff] [blame] | 197 | \function{raw_input()} is waiting for input also raise this |
Barry Warsaw | da00c87 | 1998-07-23 19:57:35 +0000 | [diff] [blame] | 198 | exception. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 199 | \end{excdesc} |
| 200 | |
| 201 | \begin{excdesc}{MemoryError} |
| 202 | Raised when an operation runs out of memory but the situation may |
| 203 | still be rescued (by deleting some objects). The associated value is |
| 204 | a string indicating what kind of (internal) operation ran out of memory. |
| 205 | Note that because of the underlying memory management architecture |
Fred Drake | 5828ad6 | 2000-04-06 15:03:01 +0000 | [diff] [blame] | 206 | (C's \cfunction{malloc()} function), the interpreter may not |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 207 | always be able to completely recover from this situation; it |
| 208 | nevertheless raises an exception so that a stack traceback can be |
| 209 | printed, in case a run-away program was the cause. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 210 | \end{excdesc} |
| 211 | |
| 212 | \begin{excdesc}{NameError} |
| 213 | Raised when a local or global name is not found. This applies only |
Raymond Hettinger | 9240be2 | 2002-08-27 23:53:23 +0000 | [diff] [blame] | 214 | to unqualified names. The associated value is an error message that |
| 215 | includes the name that could not be found. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 216 | \end{excdesc} |
| 217 | |
Barry Warsaw | 6d26f4b | 1998-12-01 19:48:04 +0000 | [diff] [blame] | 218 | \begin{excdesc}{NotImplementedError} |
Barry Warsaw | 6d26f4b | 1998-12-01 19:48:04 +0000 | [diff] [blame] | 219 | This exception is derived from \exception{RuntimeError}. In user |
| 220 | defined base classes, abstract methods should raise this exception |
| 221 | when they require derived classes to override the method. |
Fred Drake | d0bceee | 1999-02-02 18:00:40 +0000 | [diff] [blame] | 222 | \versionadded{1.5.2} |
Barry Warsaw | 6d26f4b | 1998-12-01 19:48:04 +0000 | [diff] [blame] | 223 | \end{excdesc} |
| 224 | |
Barry Warsaw | da00c87 | 1998-07-23 19:57:35 +0000 | [diff] [blame] | 225 | \begin{excdesc}{OSError} |
| 226 | %xref for os module |
Fred Drake | c457ca7 | 1998-07-23 20:31:53 +0000 | [diff] [blame] | 227 | This class is derived from \exception{EnvironmentError} and is used |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 228 | primarily as the \refmodule{os} module's \code{os.error} exception. |
Fred Drake | 98be47e | 1999-02-01 16:17:40 +0000 | [diff] [blame] | 229 | See \exception{EnvironmentError} above for a description of the |
| 230 | possible associated values. |
Fred Drake | d0bceee | 1999-02-02 18:00:40 +0000 | [diff] [blame] | 231 | \versionadded{1.5.2} |
Barry Warsaw | da00c87 | 1998-07-23 19:57:35 +0000 | [diff] [blame] | 232 | \end{excdesc} |
| 233 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 234 | \begin{excdesc}{OverflowError} |
| 235 | % XXXJH reference to long's and/or int's? |
| 236 | Raised when the result of an arithmetic operation is too large to be |
| 237 | represented. This cannot occur for long integers (which would rather |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 238 | raise \exception{MemoryError} than give up). Because of the lack of |
Fred Drake | 5828ad6 | 2000-04-06 15:03:01 +0000 | [diff] [blame] | 239 | standardization of floating point exception handling in C, most |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 240 | floating point operations also aren't checked. For plain integers, |
| 241 | all operations that can overflow are checked except left shift, where |
| 242 | typical applications prefer to drop bits than raise an exception. |
| 243 | \end{excdesc} |
| 244 | |
Fred Drake | 8c2c3d3 | 2001-10-06 06:10:54 +0000 | [diff] [blame] | 245 | \begin{excdesc}{ReferenceError} |
| 246 | This exception is raised when a weak reference proxy, created by the |
| 247 | \function{\refmodule{weakref}.proxy()} function, is used to access |
| 248 | an attribute of the referent after it has been garbage collected. |
| 249 | For more information on weak references, see the \refmodule{weakref} |
| 250 | module. |
| 251 | \versionadded[Previously known as the |
| 252 | \exception{\refmodule{weakref}.ReferenceError} |
| 253 | exception]{2.2} |
| 254 | \end{excdesc} |
| 255 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 256 | \begin{excdesc}{RuntimeError} |
| 257 | Raised when an error is detected that doesn't fall in any of the |
| 258 | other categories. The associated value is a string indicating what |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 259 | precisely went wrong. (This exception is mostly a relic from a |
| 260 | previous version of the interpreter; it is not used very much any |
| 261 | more.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 262 | \end{excdesc} |
| 263 | |
Fred Drake | 9cfe182 | 2001-05-03 04:30:45 +0000 | [diff] [blame] | 264 | \begin{excdesc}{StopIteration} |
| 265 | Raised by an iterator's \method{next()} method to signal that there |
| 266 | are no further values. |
| 267 | This is derived from \exception{Exception} rather than |
| 268 | \exception{StandardError}, since this is not considered an error in |
| 269 | its normal application. |
Fred Drake | f42cc45 | 2001-05-03 04:39:10 +0000 | [diff] [blame] | 270 | \versionadded{2.2} |
Fred Drake | 9cfe182 | 2001-05-03 04:30:45 +0000 | [diff] [blame] | 271 | \end{excdesc} |
| 272 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 273 | \begin{excdesc}{SyntaxError} |
| 274 | % XXXJH xref to these functions? |
| 275 | Raised when the parser encounters a syntax error. This may occur in |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 276 | an \keyword{import} statement, in an \keyword{exec} statement, in a call |
| 277 | to the built-in function \function{eval()} or \function{input()}, or |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 278 | when reading the initial script or standard input (also |
| 279 | interactively). |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 280 | |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame] | 281 | Instances of this class have attributes \member{filename}, |
Fred Drake | c692055 | 2001-09-21 21:12:30 +0000 | [diff] [blame] | 282 | \member{lineno}, \member{offset} and \member{text} for easier access |
| 283 | to the details. \function{str()} of the exception instance returns |
| 284 | only the message. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 285 | \end{excdesc} |
| 286 | |
| 287 | \begin{excdesc}{SystemError} |
| 288 | Raised when the interpreter finds an internal error, but the |
| 289 | situation does not look so serious to cause it to abandon all hope. |
| 290 | The associated value is a string indicating what went wrong (in |
| 291 | low-level terms). |
| 292 | |
| 293 | You should report this to the author or maintainer of your Python |
Fred Drake | c692055 | 2001-09-21 21:12:30 +0000 | [diff] [blame] | 294 | interpreter. Be sure to report the version of the Python |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 295 | interpreter (\code{sys.version}; it is also printed at the start of an |
| 296 | interactive Python session), the exact error message (the exception's |
| 297 | associated value) and if possible the source of the program that |
| 298 | triggered the error. |
| 299 | \end{excdesc} |
| 300 | |
| 301 | \begin{excdesc}{SystemExit} |
| 302 | % XXXJH xref to module sys? |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 303 | This exception is raised by the \function{sys.exit()} function. When it |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 304 | is not handled, the Python interpreter exits; no stack traceback is |
| 305 | printed. If the associated value is a plain integer, it specifies the |
Fred Drake | 5828ad6 | 2000-04-06 15:03:01 +0000 | [diff] [blame] | 306 | system exit status (passed to C's \cfunction{exit()} function); if it is |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 307 | \code{None}, the exit status is zero; if it has another type (such as |
| 308 | a string), the object's value is printed and the exit status is one. |
Guido van Rossum | df3dba0 | 1997-10-05 18:51:26 +0000 | [diff] [blame] | 309 | |
Fred Drake | 5828ad6 | 2000-04-06 15:03:01 +0000 | [diff] [blame] | 310 | Instances have an attribute \member{code} which is set to the |
| 311 | proposed exit status or error message (defaulting to \code{None}). |
| 312 | Also, this exception derives directly from \exception{Exception} and |
| 313 | not \exception{StandardError}, since it is not technically an error. |
| 314 | |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 315 | A call to \function{sys.exit()} is translated into an exception so that |
| 316 | clean-up handlers (\keyword{finally} clauses of \keyword{try} statements) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 317 | can be executed, and so that a debugger can execute a script without |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 318 | running the risk of losing control. The \function{os._exit()} function |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 319 | can be used if it is absolutely positively necessary to exit |
Fred Drake | c046e97 | 2001-07-23 19:19:39 +0000 | [diff] [blame] | 320 | immediately (for example, in the child process after a call to |
| 321 | \function{fork()}). |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 322 | \end{excdesc} |
| 323 | |
| 324 | \begin{excdesc}{TypeError} |
Raymond Hettinger | 4ee2ff3 | 2003-08-04 08:33:50 +0000 | [diff] [blame] | 325 | Raised when an operation or function is applied to an object |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 326 | of inappropriate type. The associated value is a string giving |
| 327 | details about the type mismatch. |
| 328 | \end{excdesc} |
| 329 | |
Fred Drake | 5828ad6 | 2000-04-06 15:03:01 +0000 | [diff] [blame] | 330 | \begin{excdesc}{UnboundLocalError} |
| 331 | Raised when a reference is made to a local variable in a function or |
| 332 | method, but no value has been bound to that variable. This is a |
| 333 | subclass of \exception{NameError}. |
Fred Drake | 30f76ff | 2000-06-30 16:06:19 +0000 | [diff] [blame] | 334 | \versionadded{2.0} |
Fred Drake | 5828ad6 | 2000-04-06 15:03:01 +0000 | [diff] [blame] | 335 | \end{excdesc} |
| 336 | |
Fred Drake | 3cb793e | 2000-04-06 14:48:35 +0000 | [diff] [blame] | 337 | \begin{excdesc}{UnicodeError} |
| 338 | Raised when a Unicode-related encoding or decoding error occurs. It |
| 339 | is a subclass of \exception{ValueError}. |
Fred Drake | 30f76ff | 2000-06-30 16:06:19 +0000 | [diff] [blame] | 340 | \versionadded{2.0} |
Fred Drake | 3cb793e | 2000-04-06 14:48:35 +0000 | [diff] [blame] | 341 | \end{excdesc} |
| 342 | |
Walter Dörwald | 3aeb632 | 2002-09-02 13:14:32 +0000 | [diff] [blame] | 343 | \begin{excdesc}{UnicodeEncodeError} |
| 344 | Raised when a Unicode-related error occurs during encoding. It |
| 345 | is a subclass of \exception{UnicodeError}. |
| 346 | \versionadded{2.3} |
| 347 | \end{excdesc} |
| 348 | |
| 349 | \begin{excdesc}{UnicodeDecodeError} |
| 350 | Raised when a Unicode-related error occurs during decoding. It |
| 351 | is a subclass of \exception{UnicodeError}. |
| 352 | \versionadded{2.3} |
| 353 | \end{excdesc} |
| 354 | |
| 355 | \begin{excdesc}{UnicodeTranslateError} |
| 356 | Raised when a Unicode-related error occurs during translating. It |
| 357 | is a subclass of \exception{UnicodeError}. |
| 358 | \versionadded{2.3} |
| 359 | \end{excdesc} |
| 360 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 361 | \begin{excdesc}{ValueError} |
| 362 | Raised when a built-in operation or function receives an argument |
| 363 | that has the right type but an inappropriate value, and the |
| 364 | situation is not described by a more precise exception such as |
Fred Drake | 27467e4 | 1998-07-23 19:47:41 +0000 | [diff] [blame] | 365 | \exception{IndexError}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 366 | \end{excdesc} |
| 367 | |
Fred Drake | cebda6f | 2000-04-17 17:42:00 +0000 | [diff] [blame] | 368 | \begin{excdesc}{WindowsError} |
| 369 | Raised when a Windows-specific error occurs or when the error number |
| 370 | does not correspond to an \cdata{errno} value. The |
| 371 | \member{errno} and \member{strerror} values are created from the |
| 372 | return values of the \cfunction{GetLastError()} and |
| 373 | \cfunction{FormatMessage()} functions from the Windows Platform API. |
| 374 | This is a subclass of \exception{OSError}. |
Fred Drake | 30f76ff | 2000-06-30 16:06:19 +0000 | [diff] [blame] | 375 | \versionadded{2.0} |
Fred Drake | cebda6f | 2000-04-17 17:42:00 +0000 | [diff] [blame] | 376 | \end{excdesc} |
| 377 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 378 | \begin{excdesc}{ZeroDivisionError} |
| 379 | Raised when the second argument of a division or modulo operation is |
| 380 | zero. The associated value is a string indicating the type of the |
| 381 | operands and the operation. |
| 382 | \end{excdesc} |
Guido van Rossum | 1367b83 | 2000-12-19 04:27:54 +0000 | [diff] [blame] | 383 | |
| 384 | |
Fred Drake | c692055 | 2001-09-21 21:12:30 +0000 | [diff] [blame] | 385 | \setindexsubitem{(built-in warning)} |
Guido van Rossum | 1367b83 | 2000-12-19 04:27:54 +0000 | [diff] [blame] | 386 | |
| 387 | The following exceptions are used as warning categories; see the |
Barry Warsaw | b8c20a7 | 2002-08-14 16:40:54 +0000 | [diff] [blame] | 388 | \refmodule{warnings} module for more information. |
Guido van Rossum | 1367b83 | 2000-12-19 04:27:54 +0000 | [diff] [blame] | 389 | |
| 390 | \begin{excdesc}{Warning} |
| 391 | Base class for warning categories. |
| 392 | \end{excdesc} |
| 393 | |
| 394 | \begin{excdesc}{UserWarning} |
| 395 | Base class for warnings generated by user code. |
| 396 | \end{excdesc} |
| 397 | |
| 398 | \begin{excdesc}{DeprecationWarning} |
| 399 | Base class for warnings about deprecated features. |
| 400 | \end{excdesc} |
| 401 | |
Neal Norwitz | d68f517 | 2002-05-29 15:54:55 +0000 | [diff] [blame] | 402 | \begin{excdesc}{PendingDeprecationWarning} |
| 403 | Base class for warnings about features which will be deprecated in the future. |
| 404 | \end{excdesc} |
| 405 | |
Guido van Rossum | 1367b83 | 2000-12-19 04:27:54 +0000 | [diff] [blame] | 406 | \begin{excdesc}{SyntaxWarning} |
| 407 | Base class for warnings about dubious syntax |
| 408 | \end{excdesc} |
| 409 | |
| 410 | \begin{excdesc}{RuntimeWarning} |
| 411 | Base class for warnings about dubious runtime behavior. |
| 412 | \end{excdesc} |
Skip Montanaro | bb6bbc4 | 2002-03-28 20:53:22 +0000 | [diff] [blame] | 413 | |
Barry Warsaw | b8c20a7 | 2002-08-14 16:40:54 +0000 | [diff] [blame] | 414 | \begin{excdesc}{FutureWarning} |
| 415 | Base class for warnings about constructs that will change semantically |
| 416 | in the future. |
| 417 | \end{excdesc} |
| 418 | |
Fred Drake | 8d62e94 | 2002-03-28 21:06:17 +0000 | [diff] [blame] | 419 | The class hierarchy for built-in exceptions is: |
Skip Montanaro | bb6bbc4 | 2002-03-28 20:53:22 +0000 | [diff] [blame] | 420 | |
| 421 | \begin{verbatim} |
| 422 | Exception |
| 423 | +-- SystemExit |
| 424 | +-- StopIteration |
| 425 | +-- StandardError |
| 426 | | +-- KeyboardInterrupt |
| 427 | | +-- ImportError |
| 428 | | +-- EnvironmentError |
| 429 | | | +-- IOError |
| 430 | | | +-- OSError |
| 431 | | | +-- WindowsError |
| 432 | | +-- EOFError |
| 433 | | +-- RuntimeError |
| 434 | | | +-- NotImplementedError |
| 435 | | +-- NameError |
| 436 | | | +-- UnboundLocalError |
| 437 | | +-- AttributeError |
| 438 | | +-- SyntaxError |
| 439 | | | +-- IndentationError |
| 440 | | | +-- TabError |
| 441 | | +-- TypeError |
| 442 | | +-- AssertionError |
| 443 | | +-- LookupError |
| 444 | | | +-- IndexError |
| 445 | | | +-- KeyError |
| 446 | | +-- ArithmeticError |
| 447 | | | +-- OverflowError |
| 448 | | | +-- ZeroDivisionError |
| 449 | | | +-- FloatingPointError |
| 450 | | +-- ValueError |
| 451 | | | +-- UnicodeError |
Walter Dörwald | 3aeb632 | 2002-09-02 13:14:32 +0000 | [diff] [blame] | 452 | | | +-- UnicodeEncodeError |
| 453 | | | +-- UnicodeDecodeError |
| 454 | | | +-- UnicodeTranslateError |
Skip Montanaro | bb6bbc4 | 2002-03-28 20:53:22 +0000 | [diff] [blame] | 455 | | +-- ReferenceError |
| 456 | | +-- SystemError |
| 457 | | +-- MemoryError |
| 458 | +---Warning |
| 459 | +-- UserWarning |
| 460 | +-- DeprecationWarning |
Neal Norwitz | d68f517 | 2002-05-29 15:54:55 +0000 | [diff] [blame] | 461 | +-- PendingDeprecationWarning |
Skip Montanaro | bb6bbc4 | 2002-03-28 20:53:22 +0000 | [diff] [blame] | 462 | +-- SyntaxWarning |
Tim Peters | c885443 | 2004-08-25 02:14:08 +0000 | [diff] [blame] | 463 | +-- OverflowWarning (not generated in 2.4; won't exist in 2.5) |
Skip Montanaro | bb6bbc4 | 2002-03-28 20:53:22 +0000 | [diff] [blame] | 464 | +-- RuntimeWarning |
Barry Warsaw | b8c20a7 | 2002-08-14 16:40:54 +0000 | [diff] [blame] | 465 | +-- FutureWarning |
Skip Montanaro | bb6bbc4 | 2002-03-28 20:53:22 +0000 | [diff] [blame] | 466 | \end{verbatim} |