blob: bef8bf1e6c8d8f415e8ab331c0a0704afd0d62aa [file] [log] [blame]
Guido van Rossum5fdeeea1994-01-02 01:22:07 +00001\section{Built-in Exceptions}
Fred Drake3bd9ab01998-07-23 19:33:08 +00002
Fred Drakeffbe6871999-04-22 21:23:22 +00003\declaremodule{standard}{exceptions}
Andrew M. Kuchling032bd0a2003-05-13 14:13:58 +00004\modulesynopsis{Standard exception classes.}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +00005
Fred Drakeb91e9341998-07-23 17:59:49 +00006
Neal Norwitz847207a2003-05-29 02:17:23 +00007Exceptions should be class objects.
Fred Drake7acb2182000-09-09 03:28:00 +00008The exceptions are defined in the module \module{exceptions}. This
9module never needs to be imported explicitly: the exceptions are
Fred Drakec6920552001-09-21 21:12:30 +000010provided in the built-in namespace as well as the \module{exceptions}
11module.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000012
Neal Norwitz847207a2003-05-29 02:17:23 +000013\begin{notice}
14In past versions of Python string exceptions were supported. In
15Python 1.5 and newer versions, all standard exceptions have been
16converted to class objects and users are encouraged to do the same.
Brett Cannon54ac2942006-03-01 22:10:49 +000017String exceptions will raise a \code{DeprecationWarning} in Python 2.5 and
18newer.
Neal Norwitz847207a2003-05-29 02:17:23 +000019In future versions, support for string exceptions will be removed.
20
Guido van Rossumdf3dba01997-10-05 18:51:26 +000021Two distinct string objects with the same value are considered different
22exceptions. This is done to force programmers to use exception names
23rather than their string value when specifying exception handlers.
24The string value of all built-in exceptions is their name, but this is
25not a requirement for user-defined exceptions or exceptions defined by
26library modules.
Neal Norwitz847207a2003-05-29 02:17:23 +000027\end{notice}
Guido van Rossumdf3dba01997-10-05 18:51:26 +000028
Fred Drake38e5d272000-04-03 20:13:55 +000029For class exceptions, in a \keyword{try}\stindex{try} statement with
30an \keyword{except}\stindex{except} clause that mentions a particular
31class, that clause also handles any exception classes derived from
32that class (but not exception classes from which \emph{it} is
33derived). Two exception classes that are not related via subclassing
34are never equivalent, even if they have the same name.
Guido van Rossumdf3dba01997-10-05 18:51:26 +000035
36The built-in exceptions listed below can be generated by the
37interpreter or built-in functions. Except where mentioned, they have
38an ``associated value'' indicating the detailed cause of the error.
39This may be a string or a tuple containing several items of
40information (e.g., an error code and a string explaining the code).
Fred Drake38e5d272000-04-03 20:13:55 +000041The associated value is the second argument to the
42\keyword{raise}\stindex{raise} statement. For string exceptions, the
43associated value itself will be stored in the variable named as the
44second argument of the \keyword{except} clause (if any). For class
45exceptions, that variable receives the exception instance. If the
46exception class is derived from the standard root class
Brett Cannon54ac2942006-03-01 22:10:49 +000047\exception{BaseException}, the associated value is present as the
48exception instance's \member{args} attribute. If there is a single argument
49(as is preferred), it is bound to the \member{message} attribute.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000050
51User code can raise built-in exceptions. This can be used to test an
Guido van Rossumdf3dba01997-10-05 18:51:26 +000052exception handler or to report an error condition ``just like'' the
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000053situation in which the interpreter raises the same exception; but
54beware that there is nothing to prevent user code from raising an
55inappropriate error.
56
Fred Drakec6920552001-09-21 21:12:30 +000057The built-in exception classes can be sub-classed to define new
58exceptions; programmers are encouraged to at least derive new
Brett Cannon54ac2942006-03-01 22:10:49 +000059exceptions from the \exception{Exception} class and not
60\exception{BaseException}. More
Fred Drakec6920552001-09-21 21:12:30 +000061information on defining exceptions is available in the
62\citetitle[../tut/tut.html]{Python Tutorial} under the heading
63``User-defined Exceptions.''
64
Fred Drake19479911998-02-13 06:58:54 +000065\setindexsubitem{(built-in exception base class)}
Guido van Rossumdf3dba01997-10-05 18:51:26 +000066
67The following exceptions are only used as base classes for other
Fred Drake5828ad62000-04-06 15:03:01 +000068exceptions.
Guido van Rossumdf3dba01997-10-05 18:51:26 +000069
Brett Cannon54ac2942006-03-01 22:10:49 +000070\begin{excdesc}{BaseException}
71The base class for all built-in exceptions. It is not meant to be directly
72inherited by user-defined classes (for that use \exception{Exception}). If
73\function{str()} or \function{unicode()} is called on an instance of this
74class, the representation of the argument(s) to the instance are returned or
75the emptry string when there were no arguments. If only a single argument is
76passed in, it is stored in the \member{message} attribute. If more than one
77argument is passed in, \member{message} is set to the empty string. These
78semantics are meant to reflect the fact that \member{message} is to store a
79text message explaining why the exception had been raised. If more data needs
80to be attached to the exception, attach it through arbitrary attributes on the
81instance. All arguments are also stored in \member{args} as a tuple, but it will
82eventually be deprecated and thus its use is discouraged.
Brett Cannon54ac2942006-03-01 22:10:49 +000083\versionadded{2.5}
Brett Cannon3096c532006-03-02 03:52:06 +000084\end{excdesc}
Brett Cannon54ac2942006-03-01 22:10:49 +000085
Guido van Rossumdf3dba01997-10-05 18:51:26 +000086\begin{excdesc}{Exception}
Brett Cannon54ac2942006-03-01 22:10:49 +000087All built-in, non-system-exiting exceptions are derived
Guido van Rossumdf3dba01997-10-05 18:51:26 +000088from this class. All user-defined exceptions should also be derived
Brett Cannon54ac2942006-03-01 22:10:49 +000089from this class.
George Yoshida2f6ce532006-05-16 18:07:00 +000090\versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
Guido van Rossumdf3dba01997-10-05 18:51:26 +000091\end{excdesc}
92
93\begin{excdesc}{StandardError}
Barry Warsawf2b45541999-02-24 00:27:14 +000094The base class for all built-in exceptions except
Brett Cannon54ac2942006-03-01 22:10:49 +000095\exception{StopIteration}, \exception{GeneratorExit},
96\exception{KeyboardInterrupt} and \exception{SystemExit}.
97\exception{StandardError} itself is derived from \exception{Exception}.
Guido van Rossumdf3dba01997-10-05 18:51:26 +000098\end{excdesc}
99
100\begin{excdesc}{ArithmeticError}
101The base class for those built-in exceptions that are raised for
Fred Drake27467e41998-07-23 19:47:41 +0000102various arithmetic errors: \exception{OverflowError},
103\exception{ZeroDivisionError}, \exception{FloatingPointError}.
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000104\end{excdesc}
105
106\begin{excdesc}{LookupError}
Barry Warsawda00c871998-07-23 19:57:35 +0000107The base class for the exceptions that are raised when a key or
Fred Drake27467e41998-07-23 19:47:41 +0000108index used on a mapping or sequence is invalid: \exception{IndexError},
Fred Drake53143be2000-10-25 21:05:29 +0000109\exception{KeyError}. This can be raised directly by
110\function{sys.setdefaultencoding()}.
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000111\end{excdesc}
112
Barry Warsawda00c871998-07-23 19:57:35 +0000113\begin{excdesc}{EnvironmentError}
114The base class for exceptions that
115can occur outside the Python system: \exception{IOError},
116\exception{OSError}. When exceptions of this type are created with a
1172-tuple, the first item is available on the instance's \member{errno}
118attribute (it is assumed to be an error number), and the second item
119is available on the \member{strerror} attribute (it is usually the
120associated error message). The tuple itself is also available on the
121\member{args} attribute.
Fred Draked0bceee1999-02-02 18:00:40 +0000122\versionadded{1.5.2}
Barry Warsawda00c871998-07-23 19:57:35 +0000123
124When an \exception{EnvironmentError} exception is instantiated with a
1253-tuple, the first two items are available as above, while the third
126item is available on the \member{filename} attribute. However, for
127backwards compatibility, the \member{args} attribute contains only a
1282-tuple of the first two constructor arguments.
129
130The \member{filename} attribute is \code{None} when this exception is
131created with other than 3 arguments. The \member{errno} and
132\member{strerror} attributes are also \code{None} when the instance was
133created with other than 2 or 3 arguments. In this last case,
134\member{args} contains the verbatim constructor arguments as a tuple.
135\end{excdesc}
136
Fred Drake88c023b2000-09-07 16:33:32 +0000137
Fred Drake19479911998-02-13 06:58:54 +0000138\setindexsubitem{(built-in exception)}
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000139
140The following exceptions are the exceptions that are actually raised.
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000141
142\begin{excdesc}{AssertionError}
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000143\stindex{assert}
Fred Drake38e5d272000-04-03 20:13:55 +0000144Raised when an \keyword{assert} statement fails.
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000145\end{excdesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000146
147\begin{excdesc}{AttributeError}
148% xref to attribute reference?
149 Raised when an attribute reference or assignment fails. (When an
Guido van Rossum470be141995-03-17 16:07:09 +0000150 object does not support attribute references or attribute assignments
Fred Drake27467e41998-07-23 19:47:41 +0000151 at all, \exception{TypeError} is raised.)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000152\end{excdesc}
153
154\begin{excdesc}{EOFError}
155% XXXJH xrefs here
Fred Drake27467e41998-07-23 19:47:41 +0000156 Raised when one of the built-in functions (\function{input()} or
Fred Drakec37b65e2001-11-28 07:26:15 +0000157 \function{raw_input()}) hits an end-of-file condition (\EOF) without
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000158 reading any data.
159% XXXJH xrefs here
Fred Drake27467e41998-07-23 19:47:41 +0000160 (N.B.: the \method{read()} and \method{readline()} methods of file
Fred Drakec37b65e2001-11-28 07:26:15 +0000161 objects return an empty string when they hit \EOF.)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000162\end{excdesc}
163
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000164\begin{excdesc}{FloatingPointError}
Fred Drakeb44e7531998-07-27 21:11:42 +0000165 Raised when a floating point operation fails. This exception is
166 always defined, but can only be raised when Python is configured
Fred Drakeee775a12000-04-11 19:46:40 +0000167 with the \longprogramopt{with-fpectl} option, or the
Fred Drakeb44e7531998-07-27 21:11:42 +0000168 \constant{WANT_SIGFPE_HANDLER} symbol is defined in the
Martin v. Löwis4f1cd8b2001-07-26 13:41:06 +0000169 \file{pyconfig.h} file.
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000170\end{excdesc}
171
Brett Cannon3096c532006-03-02 03:52:06 +0000172\begin{excdesc}{GeneratorExit}
Brett Cannon54ac2942006-03-01 22:10:49 +0000173 Raise when a generator's \method{close()} method is called.
174 It directly inherits from \exception{Exception} instead of
175 \exception{StandardError} since it is technically not an error.
176 \versionadded{2.5}
Brett Cannon3096c532006-03-02 03:52:06 +0000177\end{excdesc}
Brett Cannon54ac2942006-03-01 22:10:49 +0000178
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000179\begin{excdesc}{IOError}
180% XXXJH xrefs here
Fred Drakeb44e7531998-07-27 21:11:42 +0000181 Raised when an I/O operation (such as a \keyword{print} statement,
182 the built-in \function{open()} function or a method of a file
183 object) fails for an I/O-related reason, e.g., ``file not found'' or
184 ``disk full''.
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000185
Fred Drake02e18b41999-01-05 21:42:18 +0000186 This class is derived from \exception{EnvironmentError}. See the
Fred Drakeb44e7531998-07-27 21:11:42 +0000187 discussion above for more information on exception instance
188 attributes.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000189\end{excdesc}
190
191\begin{excdesc}{ImportError}
192% XXXJH xref to import statement?
Fred Drake27467e41998-07-23 19:47:41 +0000193 Raised when an \keyword{import} statement fails to find the module
Fred Drakef65e3231998-11-25 20:55:03 +0000194 definition or when a \code{from \textrm{\ldots} import} fails to find a
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000195 name that is to be imported.
196\end{excdesc}
197
198\begin{excdesc}{IndexError}
199% XXXJH xref to sequences
200 Raised when a sequence subscript is out of range. (Slice indices are
201 silently truncated to fall in the allowed range; if an index is not a
Fred Drake27467e41998-07-23 19:47:41 +0000202 plain integer, \exception{TypeError} is raised.)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000203\end{excdesc}
204
205\begin{excdesc}{KeyError}
206% XXXJH xref to mapping objects?
207 Raised when a mapping (dictionary) key is not found in the set of
208 existing keys.
209\end{excdesc}
210
211\begin{excdesc}{KeyboardInterrupt}
212 Raised when the user hits the interrupt key (normally
Fred Drake682d5f32001-07-12 02:09:51 +0000213 \kbd{Control-C} or \kbd{Delete}). During execution, a check for
Fred Drake2a1cc3e1998-04-28 13:38:54 +0000214 interrupts is made regularly.
Brett Cannon54ac2942006-03-01 22:10:49 +0000215% XXX(hylton) xrefs here
Fred Drake2a1cc3e1998-04-28 13:38:54 +0000216 Interrupts typed when a built-in function \function{input()} or
Raymond Hettingerb4c1d9b2003-05-10 08:51:28 +0000217 \function{raw_input()} is waiting for input also raise this
Barry Warsawda00c871998-07-23 19:57:35 +0000218 exception.
Brett Cannon54ac2942006-03-01 22:10:49 +0000219 The exception inherits from \exception{BaseException} so as to not be
220 accidentally caught by code that catches \exception{Exception} and thus
221 prevent the interpreter from exiting.
222 \versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000223\end{excdesc}
224
225\begin{excdesc}{MemoryError}
226 Raised when an operation runs out of memory but the situation may
227 still be rescued (by deleting some objects). The associated value is
228 a string indicating what kind of (internal) operation ran out of memory.
229 Note that because of the underlying memory management architecture
Fred Drake5828ad62000-04-06 15:03:01 +0000230 (C's \cfunction{malloc()} function), the interpreter may not
Fred Drake27467e41998-07-23 19:47:41 +0000231 always be able to completely recover from this situation; it
232 nevertheless raises an exception so that a stack traceback can be
233 printed, in case a run-away program was the cause.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000234\end{excdesc}
235
236\begin{excdesc}{NameError}
237 Raised when a local or global name is not found. This applies only
Raymond Hettinger9240be22002-08-27 23:53:23 +0000238 to unqualified names. The associated value is an error message that
239 includes the name that could not be found.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000240\end{excdesc}
241
Barry Warsaw6d26f4b1998-12-01 19:48:04 +0000242\begin{excdesc}{NotImplementedError}
Barry Warsaw6d26f4b1998-12-01 19:48:04 +0000243 This exception is derived from \exception{RuntimeError}. In user
244 defined base classes, abstract methods should raise this exception
245 when they require derived classes to override the method.
Fred Draked0bceee1999-02-02 18:00:40 +0000246 \versionadded{1.5.2}
Barry Warsaw6d26f4b1998-12-01 19:48:04 +0000247\end{excdesc}
248
Barry Warsawda00c871998-07-23 19:57:35 +0000249\begin{excdesc}{OSError}
250 %xref for os module
Fred Drakec457ca71998-07-23 20:31:53 +0000251 This class is derived from \exception{EnvironmentError} and is used
Fred Drakeffbe6871999-04-22 21:23:22 +0000252 primarily as the \refmodule{os} module's \code{os.error} exception.
Fred Drake98be47e1999-02-01 16:17:40 +0000253 See \exception{EnvironmentError} above for a description of the
254 possible associated values.
Fred Draked0bceee1999-02-02 18:00:40 +0000255 \versionadded{1.5.2}
Barry Warsawda00c871998-07-23 19:57:35 +0000256\end{excdesc}
257
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000258\begin{excdesc}{OverflowError}
259% XXXJH reference to long's and/or int's?
260 Raised when the result of an arithmetic operation is too large to be
261 represented. This cannot occur for long integers (which would rather
Fred Drake27467e41998-07-23 19:47:41 +0000262 raise \exception{MemoryError} than give up). Because of the lack of
Fred Drake5828ad62000-04-06 15:03:01 +0000263 standardization of floating point exception handling in C, most
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000264 floating point operations also aren't checked. For plain integers,
265 all operations that can overflow are checked except left shift, where
266 typical applications prefer to drop bits than raise an exception.
267\end{excdesc}
268
Fred Drake8c2c3d32001-10-06 06:10:54 +0000269\begin{excdesc}{ReferenceError}
270 This exception is raised when a weak reference proxy, created by the
271 \function{\refmodule{weakref}.proxy()} function, is used to access
272 an attribute of the referent after it has been garbage collected.
273 For more information on weak references, see the \refmodule{weakref}
274 module.
275 \versionadded[Previously known as the
276 \exception{\refmodule{weakref}.ReferenceError}
277 exception]{2.2}
278\end{excdesc}
279
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000280\begin{excdesc}{RuntimeError}
281 Raised when an error is detected that doesn't fall in any of the
282 other categories. The associated value is a string indicating what
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000283 precisely went wrong. (This exception is mostly a relic from a
284 previous version of the interpreter; it is not used very much any
285 more.)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000286\end{excdesc}
287
Fred Drake9cfe1822001-05-03 04:30:45 +0000288\begin{excdesc}{StopIteration}
289 Raised by an iterator's \method{next()} method to signal that there
290 are no further values.
291 This is derived from \exception{Exception} rather than
292 \exception{StandardError}, since this is not considered an error in
293 its normal application.
Fred Drakef42cc452001-05-03 04:39:10 +0000294 \versionadded{2.2}
Fred Drake9cfe1822001-05-03 04:30:45 +0000295\end{excdesc}
296
Brett Cannon54ac2942006-03-01 22:10:49 +0000297
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000298\begin{excdesc}{SyntaxError}
299% XXXJH xref to these functions?
300 Raised when the parser encounters a syntax error. This may occur in
Fred Drake27467e41998-07-23 19:47:41 +0000301 an \keyword{import} statement, in an \keyword{exec} statement, in a call
302 to the built-in function \function{eval()} or \function{input()}, or
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000303 when reading the initial script or standard input (also
304 interactively).
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000305
Raymond Hettinger68804312005-01-01 00:28:46 +0000306 Instances of this class have attributes \member{filename},
Fred Drakec6920552001-09-21 21:12:30 +0000307 \member{lineno}, \member{offset} and \member{text} for easier access
308 to the details. \function{str()} of the exception instance returns
309 only the message.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000310\end{excdesc}
311
312\begin{excdesc}{SystemError}
313 Raised when the interpreter finds an internal error, but the
314 situation does not look so serious to cause it to abandon all hope.
315 The associated value is a string indicating what went wrong (in
316 low-level terms).
317
318 You should report this to the author or maintainer of your Python
Fred Drakec6920552001-09-21 21:12:30 +0000319 interpreter. Be sure to report the version of the Python
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000320 interpreter (\code{sys.version}; it is also printed at the start of an
321 interactive Python session), the exact error message (the exception's
322 associated value) and if possible the source of the program that
323 triggered the error.
324\end{excdesc}
325
326\begin{excdesc}{SystemExit}
Brett Cannon54ac2942006-03-01 22:10:49 +0000327% XXX(hylton) xref to module sys?
Fred Drake27467e41998-07-23 19:47:41 +0000328 This exception is raised by the \function{sys.exit()} function. When it
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000329 is not handled, the Python interpreter exits; no stack traceback is
330 printed. If the associated value is a plain integer, it specifies the
Fred Drake5828ad62000-04-06 15:03:01 +0000331 system exit status (passed to C's \cfunction{exit()} function); if it is
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000332 \code{None}, the exit status is zero; if it has another type (such as
333 a string), the object's value is printed and the exit status is one.
Guido van Rossumdf3dba01997-10-05 18:51:26 +0000334
Fred Drake5828ad62000-04-06 15:03:01 +0000335 Instances have an attribute \member{code} which is set to the
336 proposed exit status or error message (defaulting to \code{None}).
Brett Cannon54ac2942006-03-01 22:10:49 +0000337 Also, this exception derives directly from \exception{BaseException} and
Fred Drake5828ad62000-04-06 15:03:01 +0000338 not \exception{StandardError}, since it is not technically an error.
339
Fred Drake27467e41998-07-23 19:47:41 +0000340 A call to \function{sys.exit()} is translated into an exception so that
341 clean-up handlers (\keyword{finally} clauses of \keyword{try} statements)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000342 can be executed, and so that a debugger can execute a script without
Fred Drake27467e41998-07-23 19:47:41 +0000343 running the risk of losing control. The \function{os._exit()} function
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000344 can be used if it is absolutely positively necessary to exit
Fred Drakec046e972001-07-23 19:19:39 +0000345 immediately (for example, in the child process after a call to
346 \function{fork()}).
Brett Cannon54ac2942006-03-01 22:10:49 +0000347
348 The exception inherits from \exception{BaseException} instead of
349 \exception{StandardError} or \exception{Exception} so that it is not
350 accidentally caught by code that catches \exception{Exception}. This allows
351 the exception to properly propagate up and cause the interpreter to exit.
352 \versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000353\end{excdesc}
354
355\begin{excdesc}{TypeError}
Raymond Hettinger4ee2ff32003-08-04 08:33:50 +0000356 Raised when an operation or function is applied to an object
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000357 of inappropriate type. The associated value is a string giving
358 details about the type mismatch.
359\end{excdesc}
360
Fred Drake5828ad62000-04-06 15:03:01 +0000361\begin{excdesc}{UnboundLocalError}
362 Raised when a reference is made to a local variable in a function or
363 method, but no value has been bound to that variable. This is a
364 subclass of \exception{NameError}.
Fred Drake30f76ff2000-06-30 16:06:19 +0000365\versionadded{2.0}
Fred Drake5828ad62000-04-06 15:03:01 +0000366\end{excdesc}
367
Fred Drake3cb793e2000-04-06 14:48:35 +0000368\begin{excdesc}{UnicodeError}
369 Raised when a Unicode-related encoding or decoding error occurs. It
370 is a subclass of \exception{ValueError}.
Fred Drake30f76ff2000-06-30 16:06:19 +0000371\versionadded{2.0}
Fred Drake3cb793e2000-04-06 14:48:35 +0000372\end{excdesc}
373
Walter Dörwald3aeb6322002-09-02 13:14:32 +0000374\begin{excdesc}{UnicodeEncodeError}
375 Raised when a Unicode-related error occurs during encoding. It
376 is a subclass of \exception{UnicodeError}.
377\versionadded{2.3}
378\end{excdesc}
379
380\begin{excdesc}{UnicodeDecodeError}
381 Raised when a Unicode-related error occurs during decoding. It
382 is a subclass of \exception{UnicodeError}.
383\versionadded{2.3}
384\end{excdesc}
385
386\begin{excdesc}{UnicodeTranslateError}
387 Raised when a Unicode-related error occurs during translating. It
388 is a subclass of \exception{UnicodeError}.
389\versionadded{2.3}
390\end{excdesc}
391
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000392\begin{excdesc}{ValueError}
393 Raised when a built-in operation or function receives an argument
394 that has the right type but an inappropriate value, and the
395 situation is not described by a more precise exception such as
Fred Drake27467e41998-07-23 19:47:41 +0000396 \exception{IndexError}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000397\end{excdesc}
398
Fred Drakecebda6f2000-04-17 17:42:00 +0000399\begin{excdesc}{WindowsError}
400 Raised when a Windows-specific error occurs or when the error number
401 does not correspond to an \cdata{errno} value. The
Martin v. Löwis879768d2006-05-11 13:28:43 +0000402 \member{winerror} and \member{strerror} values are created from the
Fred Drakecebda6f2000-04-17 17:42:00 +0000403 return values of the \cfunction{GetLastError()} and
404 \cfunction{FormatMessage()} functions from the Windows Platform API.
Martin v. Löwis879768d2006-05-11 13:28:43 +0000405 The \member{errno} value maps the \member{winerror} value to
406 corresponding \code{errno.h} values.
Fred Drakecebda6f2000-04-17 17:42:00 +0000407 This is a subclass of \exception{OSError}.
Fred Drake30f76ff2000-06-30 16:06:19 +0000408\versionadded{2.0}
Martin v. Löwis879768d2006-05-11 13:28:43 +0000409\versionchanged[Previous versions put the \cfunction{GetLastError()}
410codes into \member{errno}]{2.5}
Fred Drakecebda6f2000-04-17 17:42:00 +0000411\end{excdesc}
412
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000413\begin{excdesc}{ZeroDivisionError}
414 Raised when the second argument of a division or modulo operation is
415 zero. The associated value is a string indicating the type of the
416 operands and the operation.
417\end{excdesc}
Guido van Rossum1367b832000-12-19 04:27:54 +0000418
419
Fred Drakec6920552001-09-21 21:12:30 +0000420\setindexsubitem{(built-in warning)}
Guido van Rossum1367b832000-12-19 04:27:54 +0000421
422The following exceptions are used as warning categories; see the
Barry Warsawb8c20a72002-08-14 16:40:54 +0000423\refmodule{warnings} module for more information.
Guido van Rossum1367b832000-12-19 04:27:54 +0000424
425\begin{excdesc}{Warning}
426Base class for warning categories.
427\end{excdesc}
428
429\begin{excdesc}{UserWarning}
430Base class for warnings generated by user code.
431\end{excdesc}
432
433\begin{excdesc}{DeprecationWarning}
434Base class for warnings about deprecated features.
435\end{excdesc}
436
Neal Norwitzd68f5172002-05-29 15:54:55 +0000437\begin{excdesc}{PendingDeprecationWarning}
438Base class for warnings about features which will be deprecated in the future.
439\end{excdesc}
440
Guido van Rossum1367b832000-12-19 04:27:54 +0000441\begin{excdesc}{SyntaxWarning}
442Base class for warnings about dubious syntax
443\end{excdesc}
444
445\begin{excdesc}{RuntimeWarning}
446Base class for warnings about dubious runtime behavior.
447\end{excdesc}
Skip Montanarobb6bbc42002-03-28 20:53:22 +0000448
Barry Warsawb8c20a72002-08-14 16:40:54 +0000449\begin{excdesc}{FutureWarning}
450Base class for warnings about constructs that will change semantically
451in the future.
452\end{excdesc}
453
George Yoshida0c8d7b02006-05-16 18:26:10 +0000454\begin{excdesc}{ImportWarning}
455Base class for warnings about probable mistakes in module imports.
456\versionadded{2.5}
457\end{excdesc}
458
Fred Drake8d62e942002-03-28 21:06:17 +0000459The class hierarchy for built-in exceptions is:
Skip Montanarobb6bbc42002-03-28 20:53:22 +0000460
Brett Cannon54ac2942006-03-01 22:10:49 +0000461\verbatiminput{../../Lib/test/exception_hierarchy.txt}