blob: 377d98ae977a6809d41f0c002f1a30f31d84a94c [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001.. _bltin-exceptions:
2
3Built-in Exceptions
4===================
5
Georg Brandl116aa622007-08-15 14:28:22 +00006.. index::
7 statement: try
8 statement: except
9
Georg Brandlfbd1b222009-12-29 21:38:35 +000010In Python, all exceptions must be instances of a class that derives from
11:class:`BaseException`. In a :keyword:`try` statement with an :keyword:`except`
Georg Brandl116aa622007-08-15 14:28:22 +000012clause that mentions a particular class, that clause also handles any exception
13classes derived from that class (but not exception classes from which *it* is
14derived). Two exception classes that are not related via subclassing are never
15equivalent, even if they have the same name.
16
17.. index:: statement: raise
18
19The built-in exceptions listed below can be generated by the interpreter or
20built-in functions. Except where mentioned, they have an "associated value"
Georg Brandlfb6fd5d2011-01-07 18:28:45 +000021indicating the detailed cause of the error. This may be a string or a tuple of
22several items of information (e.g., an error code and a string explaining the
23code). The associated value is usually passed as arguments to the exception
24class's constructor.
Georg Brandl116aa622007-08-15 14:28:22 +000025
26User code can raise built-in exceptions. This can be used to test an exception
27handler or to report an error condition "just like" the situation in which the
28interpreter raises the same exception; but beware that there is nothing to
29prevent user code from raising an inappropriate error.
30
31The built-in exception classes can be sub-classed to define new exceptions;
32programmers are encouraged to at least derive new exceptions from the
33:exc:`Exception` class and not :exc:`BaseException`. More information on
34defining exceptions is available in the Python Tutorial under
35:ref:`tut-userexceptions`.
36
Nick Coghlanab7bf212012-02-26 17:49:52 +100037When raising (or re-raising) an exception in an :keyword:`except` clause
38:attr:`__context__` is automatically set to the last exception caught; if the
39new exception is not handled the traceback that is eventually displayed will
40include the originating exception(s) and the final exception.
41
Nick Coghlan0eee97c2012-12-09 16:21:46 +100042When raising a new exception (rather than using a bare ``raise`` to re-raise
43the exception currently being handled), the implicit exception context can be
44supplemented with an explicit cause by using :keyword:`from` with
45:keyword:`raise`::
46
47 raise new_exc from original_exc
48
49The expression following :keyword:`from` must be an exception or ``None``. It
50will be set as :attr:`__cause__` on the raised exception. Setting
51:attr:`__cause__` also implicitly sets the :attr:`__suppress_context__`
52attribute to ``True``, so that using ``raise new_exc from None``
53effectively replaces the old exception with the new one for display
54purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`, while
55leaving the old exception available in :attr:`__context__` for introspection
56when debugging.
Nick Coghlanab7bf212012-02-26 17:49:52 +100057
Nick Coghlan8e18fc82012-12-08 21:39:24 +100058The default traceback display code shows these chained exceptions in
59addition to the traceback for the exception itself. An explicitly chained
60exception in :attr:`__cause__` is always shown when present. An implicitly
61chained exception in :attr:`__context__` is shown only if :attr:`__cause__`
Nick Coghlan0eee97c2012-12-09 16:21:46 +100062is :const:`None` and :attr:`__suppress_context__` is false.
Nick Coghlan8e18fc82012-12-08 21:39:24 +100063
64In either case, the exception itself is always shown after any chained
65exceptions so that the final line of the traceback always shows the last
66exception that was raised.
Nick Coghlanab7bf212012-02-26 17:49:52 +100067
Antoine Pitrouf9c77462011-10-12 16:02:00 +020068
69Base classes
70------------
71
Georg Brandlfbd1b222009-12-29 21:38:35 +000072The following exceptions are used mostly as base classes for other exceptions.
Georg Brandl116aa622007-08-15 14:28:22 +000073
Georg Brandl116aa622007-08-15 14:28:22 +000074.. exception:: BaseException
75
76 The base class for all built-in exceptions. It is not meant to be directly
Georg Brandlfb6fd5d2011-01-07 18:28:45 +000077 inherited by user-defined classes (for that, use :exc:`Exception`). If
Amaury Forgeot d'Arc3b1acf12011-11-22 19:34:08 +010078 :func:`str` is called on an instance of this class, the representation of
79 the argument(s) to the instance are returned, or the empty string when
80 there were no arguments.
Georg Brandlfb6fd5d2011-01-07 18:28:45 +000081
82 .. attribute:: args
83
84 The tuple of arguments given to the exception constructor. Some built-in
85 exceptions (like :exc:`IOError`) expect a certain number of arguments and
86 assign a special meaning to the elements of this tuple, while others are
87 usually called only with a single string giving an error message.
88
89 .. method:: with_traceback(tb)
90
91 This method sets *tb* as the new traceback for the exception and returns
92 the exception object. It is usually used in exception handling code like
93 this::
94
95 try:
96 ...
97 except SomeException:
98 tb = sys.exc_info()[2]
99 raise OtherException(...).with_traceback(tb)
Georg Brandl116aa622007-08-15 14:28:22 +0000100
Georg Brandl116aa622007-08-15 14:28:22 +0000101
102.. exception:: Exception
103
104 All built-in, non-system-exiting exceptions are derived from this class. All
105 user-defined exceptions should also be derived from this class.
106
Georg Brandl116aa622007-08-15 14:28:22 +0000107
108.. exception:: ArithmeticError
109
110 The base class for those built-in exceptions that are raised for various
111 arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`,
112 :exc:`FloatingPointError`.
113
114
Georg Brandl0bdfbfa2010-12-18 17:51:28 +0000115.. exception:: BufferError
116
117 Raised when a :ref:`buffer <bufferobjects>` related operation cannot be
118 performed.
119
120
Georg Brandl116aa622007-08-15 14:28:22 +0000121.. exception:: LookupError
122
Benjamin Petersonfa0d7032009-06-01 22:42:33 +0000123 The base class for the exceptions that are raised when a key or index used on
124 a mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`. This
125 can be raised directly by :func:`codecs.lookup`.
Georg Brandl116aa622007-08-15 14:28:22 +0000126
127
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200128Concrete exceptions
129-------------------
Georg Brandl116aa622007-08-15 14:28:22 +0000130
Georg Brandlfbd1b222009-12-29 21:38:35 +0000131The following exceptions are the exceptions that are usually raised.
Georg Brandl116aa622007-08-15 14:28:22 +0000132
133.. exception:: AssertionError
134
135 .. index:: statement: assert
136
137 Raised when an :keyword:`assert` statement fails.
138
139
140.. exception:: AttributeError
141
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000142 Raised when an attribute reference (see :ref:`attribute-references`) or
143 assignment fails. (When an object does not support attribute references or
144 attribute assignments at all, :exc:`TypeError` is raised.)
Georg Brandl116aa622007-08-15 14:28:22 +0000145
146
147.. exception:: EOFError
148
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000149 Raised when one of the built-in functions (:func:`input` or :func:`raw_input`)
150 hits an end-of-file condition (EOF) without reading any data. (N.B.: the
Georg Brandl81ac1ce2007-08-31 17:17:17 +0000151 :meth:`file.read` and :meth:`file.readline` methods return an empty string
152 when they hit EOF.)
Georg Brandl116aa622007-08-15 14:28:22 +0000153
154
155.. exception:: FloatingPointError
156
157 Raised when a floating point operation fails. This exception is always defined,
158 but can only be raised when Python is configured with the
Éric Araujo713d3032010-11-18 16:38:46 +0000159 ``--with-fpectl`` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
Georg Brandl116aa622007-08-15 14:28:22 +0000160 defined in the :file:`pyconfig.h` file.
161
162
163.. exception:: GeneratorExit
164
Christian Heimescbf3b5c2007-12-03 21:02:03 +0000165 Raise when a :term:`generator`\'s :meth:`close` method is called. It
166 directly inherits from :exc:`BaseException` instead of :exc:`Exception` since
167 it is technically not an error.
Georg Brandl116aa622007-08-15 14:28:22 +0000168
Georg Brandl116aa622007-08-15 14:28:22 +0000169
Georg Brandl116aa622007-08-15 14:28:22 +0000170.. exception:: ImportError
171
Brett Cannonb1611e22013-06-12 16:59:46 -0400172 Raised when the :keyword:`import` statement has troubles trying to load a
173 module.
Georg Brandl116aa622007-08-15 14:28:22 +0000174
Brett Cannon79ec55e2012-04-12 20:24:54 -0400175 The :attr:`name` and :attr:`path` attributes can be set using keyword-only
176 arguments to the constructor. When set they represent the name of the module
177 that was attempted to be imported and the path to any file which triggered
178 the exception, respectively.
179
180 .. versionchanged:: 3.3
181 Added the :attr:`name` and :attr:`path` attributes.
182
Brett Cannonb1611e22013-06-12 16:59:46 -0400183.. exception:: ModuleNotFoundError
184
185 A subclass of :exc:`ImportError` which is raised by :keyword:`import` when a
186 module could not be located. This includes ``from ... import`` statements as
187 the specific attribute being requested cannot be known a priori to be a module
Brett Cannon8f5ac512013-06-12 23:29:18 -0400188 or some other type of object. It is also raised when ``None`` is found in
189 :data:`sys.modules`.
Brett Cannonb1611e22013-06-12 16:59:46 -0400190
191 .. versionadded:: 3.4
192
Georg Brandl116aa622007-08-15 14:28:22 +0000193
194.. exception:: IndexError
195
Georg Brandl95817b32008-05-11 14:30:18 +0000196 Raised when a sequence subscript is out of range. (Slice indices are
197 silently truncated to fall in the allowed range; if an index is not an
198 integer, :exc:`TypeError` is raised.)
Georg Brandl116aa622007-08-15 14:28:22 +0000199
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000200 .. XXX xref to sequences
Georg Brandl116aa622007-08-15 14:28:22 +0000201
202
203.. exception:: KeyError
204
205 Raised when a mapping (dictionary) key is not found in the set of existing keys.
206
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000207 .. XXX xref to mapping objects?
Georg Brandl116aa622007-08-15 14:28:22 +0000208
209
210.. exception:: KeyboardInterrupt
211
212 Raised when the user hits the interrupt key (normally :kbd:`Control-C` or
Georg Brandl81ac1ce2007-08-31 17:17:17 +0000213 :kbd:`Delete`). During execution, a check for interrupts is made
214 regularly. The exception inherits from :exc:`BaseException` so as to not be
215 accidentally caught by code that catches :exc:`Exception` and thus prevent
216 the interpreter from exiting.
Georg Brandl116aa622007-08-15 14:28:22 +0000217
Georg Brandl116aa622007-08-15 14:28:22 +0000218
219.. exception:: MemoryError
220
221 Raised when an operation runs out of memory but the situation may still be
222 rescued (by deleting some objects). The associated value is a string indicating
223 what kind of (internal) operation ran out of memory. Note that because of the
Georg Brandl60203b42010-10-06 10:11:56 +0000224 underlying memory management architecture (C's :c:func:`malloc` function), the
Georg Brandl116aa622007-08-15 14:28:22 +0000225 interpreter may not always be able to completely recover from this situation; it
226 nevertheless raises an exception so that a stack traceback can be printed, in
227 case a run-away program was the cause.
228
229
230.. exception:: NameError
231
232 Raised when a local or global name is not found. This applies only to
233 unqualified names. The associated value is an error message that includes the
234 name that could not be found.
235
236
237.. exception:: NotImplementedError
238
239 This exception is derived from :exc:`RuntimeError`. In user defined base
240 classes, abstract methods should raise this exception when they require derived
241 classes to override the method.
242
Georg Brandl116aa622007-08-15 14:28:22 +0000243
244.. exception:: OSError
245
Christian Heimesa62da1d2008-01-12 19:39:10 +0000246 .. index:: module: errno
247
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200248 This exception is raised when a system function returns a system-related
249 error, including I/O failures such as "file not found" or "disk full"
250 (not for illegal argument types or other incidental errors). Often a
251 subclass of :exc:`OSError` will actually be raised as described in
252 `OS exceptions`_ below. The :attr:`errno` attribute is a numeric error
253 code from the C variable :c:data:`errno`.
Christian Heimesa62da1d2008-01-12 19:39:10 +0000254
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200255 Under Windows, the :attr:`winerror` attribute gives you the native
256 Windows error code. The :attr:`errno` attribute is then an approximate
257 translation, in POSIX terms, of that native error code.
258
259 Under all platforms, the :attr:`strerror` attribute is the corresponding
260 error message as provided by the operating system (as formatted by the C
261 functions :c:func:`perror` under POSIX, and :c:func:`FormatMessage`
262 Windows).
263
264 For exceptions that involve a file system path (such as :func:`open` or
265 :func:`os.unlink`), the exception instance will contain an additional
266 attribute, :attr:`filename`, which is the file name passed to the function.
Georg Brandl116aa622007-08-15 14:28:22 +0000267
Antoine Pitrou195e7022011-10-12 16:46:46 +0200268 .. versionchanged:: 3.3
269 :exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`,
270 :exc:`VMSError`, :exc:`socket.error`, :exc:`select.error` and
271 :exc:`mmap.error` have been merged into :exc:`OSError`.
272
Victor Stinner292c8352012-10-30 02:17:38 +0100273 .. versionchanged:: 3.4
274
275 The :attr:`filename` attribute is now the original file name passed to
276 the function, instead of the name encoded to or decoded from the
277 filesystem encoding.
278
Georg Brandl116aa622007-08-15 14:28:22 +0000279
280.. exception:: OverflowError
281
282 Raised when the result of an arithmetic operation is too large to be
Georg Brandlba956ae2007-11-29 17:24:34 +0000283 represented. This cannot occur for integers (which would rather raise
Georg Brandl116aa622007-08-15 14:28:22 +0000284 :exc:`MemoryError` than give up). Because of the lack of standardization of
285 floating point exception handling in C, most floating point operations also
Georg Brandl81ac1ce2007-08-31 17:17:17 +0000286 aren't checked.
Georg Brandl116aa622007-08-15 14:28:22 +0000287
288
289.. exception:: ReferenceError
290
291 This exception is raised when a weak reference proxy, created by the
292 :func:`weakref.proxy` function, is used to access an attribute of the referent
293 after it has been garbage collected. For more information on weak references,
294 see the :mod:`weakref` module.
295
Georg Brandl116aa622007-08-15 14:28:22 +0000296
297.. exception:: RuntimeError
298
299 Raised when an error is detected that doesn't fall in any of the other
300 categories. The associated value is a string indicating what precisely went
301 wrong. (This exception is mostly a relic from a previous version of the
302 interpreter; it is not used very much any more.)
303
304
305.. exception:: StopIteration
306
Georg Brandlc4a55fc2010-02-06 18:46:57 +0000307 Raised by built-in function :func:`next` and an :term:`iterator`\'s
Ezio Melotti1dd7c302012-10-12 13:45:38 +0300308 :meth:`~iterator.__next__` method to signal that there are no further
309 items produced by the iterator.
Nick Coghlan1f7ce622012-01-13 21:43:40 +1000310
311 The exception object has a single attribute :attr:`value`, which is
312 given as an argument when constructing the exception, and defaults
313 to :const:`None`.
314
315 When a generator function returns, a new :exc:`StopIteration` instance is
316 raised, and the value returned by the function is used as the
317 :attr:`value` parameter to the constructor of the exception.
Georg Brandl116aa622007-08-15 14:28:22 +0000318
Nick Coghlan0ed80192012-01-14 14:43:24 +1000319 .. versionchanged:: 3.3
320 Added ``value`` attribute and the ability for generator functions to
321 use it to return a value.
Georg Brandl116aa622007-08-15 14:28:22 +0000322
323.. exception:: SyntaxError
324
325 Raised when the parser encounters a syntax error. This may occur in an
326 :keyword:`import` statement, in a call to the built-in functions :func:`exec`
327 or :func:`eval`, or when reading the initial script or standard input
328 (also interactively).
329
Georg Brandl116aa622007-08-15 14:28:22 +0000330 Instances of this class have attributes :attr:`filename`, :attr:`lineno`,
331 :attr:`offset` and :attr:`text` for easier access to the details. :func:`str`
332 of the exception instance returns only the message.
333
334
Georg Brandl0bdfbfa2010-12-18 17:51:28 +0000335.. exception:: IndentationError
336
337 Base class for syntax errors related to incorrect indentation. This is a
338 subclass of :exc:`SyntaxError`.
339
340
341.. exception:: TabError
342
343 Raised when indentation contains an inconsistent use of tabs and spaces.
344 This is a subclass of :exc:`IndentationError`.
345
346
Georg Brandl116aa622007-08-15 14:28:22 +0000347.. exception:: SystemError
348
349 Raised when the interpreter finds an internal error, but the situation does not
350 look so serious to cause it to abandon all hope. The associated value is a
351 string indicating what went wrong (in low-level terms).
352
353 You should report this to the author or maintainer of your Python interpreter.
354 Be sure to report the version of the Python interpreter (``sys.version``; it is
355 also printed at the start of an interactive Python session), the exact error
356 message (the exception's associated value) and if possible the source of the
357 program that triggered the error.
358
359
360.. exception:: SystemExit
361
362 This exception is raised by the :func:`sys.exit` function. When it is not
363 handled, the Python interpreter exits; no stack traceback is printed. If the
Georg Brandl95817b32008-05-11 14:30:18 +0000364 associated value is an integer, it specifies the system exit status (passed
Georg Brandl60203b42010-10-06 10:11:56 +0000365 to C's :c:func:`exit` function); if it is ``None``, the exit status is zero;
Georg Brandl95817b32008-05-11 14:30:18 +0000366 if it has another type (such as a string), the object's value is printed and
367 the exit status is one.
Georg Brandl116aa622007-08-15 14:28:22 +0000368
Georg Brandl116aa622007-08-15 14:28:22 +0000369 Instances have an attribute :attr:`code` which is set to the proposed exit
370 status or error message (defaulting to ``None``). Also, this exception derives
371 directly from :exc:`BaseException` and not :exc:`Exception`, since it is not
372 technically an error.
373
374 A call to :func:`sys.exit` is translated into an exception so that clean-up
375 handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be
376 executed, and so that a debugger can execute a script without running the risk
377 of losing control. The :func:`os._exit` function can be used if it is
378 absolutely positively necessary to exit immediately (for example, in the child
379 process after a call to :func:`fork`).
380
381 The exception inherits from :exc:`BaseException` instead of :exc:`Exception` so
382 that it is not accidentally caught by code that catches :exc:`Exception`. This
383 allows the exception to properly propagate up and cause the interpreter to exit.
384
Georg Brandl116aa622007-08-15 14:28:22 +0000385
386.. exception:: TypeError
387
388 Raised when an operation or function is applied to an object of inappropriate
389 type. The associated value is a string giving details about the type mismatch.
390
391
392.. exception:: UnboundLocalError
393
394 Raised when a reference is made to a local variable in a function or method, but
395 no value has been bound to that variable. This is a subclass of
396 :exc:`NameError`.
397
Georg Brandl116aa622007-08-15 14:28:22 +0000398
399.. exception:: UnicodeError
400
401 Raised when a Unicode-related encoding or decoding error occurs. It is a
402 subclass of :exc:`ValueError`.
403
Benjamin Peterson78f7e3a2012-12-02 11:33:06 -0500404 :exc:`UnicodeError` has attributes that describe the encoding or decoding
405 error. For example, ``err.object[err.start:err.end]`` gives the particular
406 invalid input that the codec failed on.
407
408 .. attribute:: encoding
409
410 The name of the encoding that raised the error.
411
412 .. attribute:: reason
413
414 A string describing the specific codec error.
415
416 .. attribute:: object
417
418 The object the codec was attempting to encode or decode.
419
420 .. attribute:: start
421
422 The first index of invalid data in :attr:`object`.
423
424 .. attribute:: end
425
426 The index after the last invalid data in :attr:`object`.
427
Georg Brandl116aa622007-08-15 14:28:22 +0000428
429.. exception:: UnicodeEncodeError
430
431 Raised when a Unicode-related error occurs during encoding. It is a subclass of
432 :exc:`UnicodeError`.
433
Georg Brandl116aa622007-08-15 14:28:22 +0000434
435.. exception:: UnicodeDecodeError
436
437 Raised when a Unicode-related error occurs during decoding. It is a subclass of
438 :exc:`UnicodeError`.
439
Georg Brandl116aa622007-08-15 14:28:22 +0000440
441.. exception:: UnicodeTranslateError
442
443 Raised when a Unicode-related error occurs during translating. It is a subclass
444 of :exc:`UnicodeError`.
445
Georg Brandl116aa622007-08-15 14:28:22 +0000446
447.. exception:: ValueError
448
449 Raised when a built-in operation or function receives an argument that has the
450 right type but an inappropriate value, and the situation is not described by a
451 more precise exception such as :exc:`IndexError`.
452
453
Georg Brandl116aa622007-08-15 14:28:22 +0000454.. exception:: ZeroDivisionError
455
456 Raised when the second argument of a division or modulo operation is zero. The
457 associated value is a string indicating the type of the operands and the
458 operation.
459
Georg Brandlfbd1b222009-12-29 21:38:35 +0000460
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200461The following exceptions are kept for compatibility with previous versions;
462starting from Python 3.3, they are aliases of :exc:`OSError`.
463
464.. exception:: EnvironmentError
465
466.. exception:: IOError
467
468.. exception:: VMSError
469
470 Only available on VMS.
471
472.. exception:: WindowsError
473
474 Only available on Windows.
475
476
477OS exceptions
478^^^^^^^^^^^^^
479
480The following exceptions are subclasses of :exc:`OSError`, they get raised
481depending on the system error code.
482
483.. exception:: BlockingIOError
484
485 Raised when an operation would block on an object (e.g. socket) set
486 for non-blocking operation.
487 Corresponds to :c:data:`errno` ``EAGAIN``, ``EALREADY``,
488 ``EWOULDBLOCK`` and ``EINPROGRESS``.
489
Antoine Pitrouf55011f2011-10-12 18:57:23 +0200490 In addition to those of :exc:`OSError`, :exc:`BlockingIOError` can have
491 one more attribute:
492
493 .. attribute:: characters_written
494
495 An integer containing the number of characters written to the stream
496 before it blocked. This attribute is available when using the
497 buffered I/O classes from the :mod:`io` module.
498
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200499.. exception:: ChildProcessError
500
501 Raised when an operation on a child process failed.
502 Corresponds to :c:data:`errno` ``ECHILD``.
503
504.. exception:: ConnectionError
505
Ezio Melottib24d3cf2012-10-21 03:22:05 +0300506 A base class for connection-related issues.
507
508 Subclasses are :exc:`BrokenPipeError`, :exc:`ConnectionAbortedError`,
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200509 :exc:`ConnectionRefusedError` and :exc:`ConnectionResetError`.
510
Ezio Melottib24d3cf2012-10-21 03:22:05 +0300511.. exception:: BrokenPipeError
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200512
Ezio Melottib24d3cf2012-10-21 03:22:05 +0300513 A subclass of :exc:`ConnectionError`, raised when trying to write on a
514 pipe while the other end has been closed, or trying to write on a socket
515 which has been shutdown for writing.
516 Corresponds to :c:data:`errno` ``EPIPE`` and ``ESHUTDOWN``.
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200517
Ezio Melottib24d3cf2012-10-21 03:22:05 +0300518.. exception:: ConnectionAbortedError
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200519
Ezio Melottib24d3cf2012-10-21 03:22:05 +0300520 A subclass of :exc:`ConnectionError`, raised when a connection attempt
521 is aborted by the peer.
522 Corresponds to :c:data:`errno` ``ECONNABORTED``.
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200523
Ezio Melottib24d3cf2012-10-21 03:22:05 +0300524.. exception:: ConnectionRefusedError
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200525
Ezio Melottib24d3cf2012-10-21 03:22:05 +0300526 A subclass of :exc:`ConnectionError`, raised when a connection attempt
527 is refused by the peer.
528 Corresponds to :c:data:`errno` ``ECONNREFUSED``.
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200529
Ezio Melottib24d3cf2012-10-21 03:22:05 +0300530.. exception:: ConnectionResetError
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200531
Ezio Melottib24d3cf2012-10-21 03:22:05 +0300532 A subclass of :exc:`ConnectionError`, raised when a connection is
533 reset by the peer.
534 Corresponds to :c:data:`errno` ``ECONNRESET``.
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200535
536.. exception:: FileExistsError
537
538 Raised when trying to create a file or directory which already exists.
539 Corresponds to :c:data:`errno` ``EEXIST``.
540
541.. exception:: FileNotFoundError
542
543 Raised when a file or directory is requested but doesn't exist.
544 Corresponds to :c:data:`errno` ``ENOENT``.
545
546.. exception:: InterruptedError
547
548 Raised when a system call is interrupted by an incoming signal.
Andrew Svetlov73a5a122012-12-05 11:12:14 +0200549 Corresponds to :c:data:`errno` ``EINTR``.
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200550
551.. exception:: IsADirectoryError
552
553 Raised when a file operation (such as :func:`os.remove`) is requested
554 on a directory.
555 Corresponds to :c:data:`errno` ``EISDIR``.
556
557.. exception:: NotADirectoryError
558
559 Raised when a directory operation (such as :func:`os.listdir`) is requested
560 on something which is not a directory.
561 Corresponds to :c:data:`errno` ``ENOTDIR``.
562
563.. exception:: PermissionError
564
565 Raised when trying to run an operation without the adequate access
566 rights - for example filesystem permissions.
567 Corresponds to :c:data:`errno` ``EACCES`` and ``EPERM``.
568
569.. exception:: ProcessLookupError
570
571 Raised when a given process doesn't exist.
572 Corresponds to :c:data:`errno` ``ESRCH``.
573
574.. exception:: TimeoutError
575
576 Raised when a system function timed out at the system level.
577 Corresponds to :c:data:`errno` ``ETIMEDOUT``.
578
579.. versionadded:: 3.3
580 All the above :exc:`OSError` subclasses were added.
581
582
583.. seealso::
584
585 :pep:`3151` - Reworking the OS and IO exception hierarchy
Antoine Pitrouf9c77462011-10-12 16:02:00 +0200586
587
588Warnings
589--------
590
Georg Brandl116aa622007-08-15 14:28:22 +0000591The following exceptions are used as warning categories; see the :mod:`warnings`
592module for more information.
593
Georg Brandl116aa622007-08-15 14:28:22 +0000594.. exception:: Warning
595
596 Base class for warning categories.
597
598
599.. exception:: UserWarning
600
601 Base class for warnings generated by user code.
602
603
604.. exception:: DeprecationWarning
605
606 Base class for warnings about deprecated features.
607
608
609.. exception:: PendingDeprecationWarning
610
611 Base class for warnings about features which will be deprecated in the future.
612
613
614.. exception:: SyntaxWarning
615
616 Base class for warnings about dubious syntax
617
618
619.. exception:: RuntimeWarning
620
621 Base class for warnings about dubious runtime behavior.
622
623
624.. exception:: FutureWarning
625
626 Base class for warnings about constructs that will change semantically in the
627 future.
628
629
630.. exception:: ImportWarning
631
632 Base class for warnings about probable mistakes in module imports.
633
Georg Brandl116aa622007-08-15 14:28:22 +0000634
635.. exception:: UnicodeWarning
636
637 Base class for warnings related to Unicode.
638
Georg Brandl08be72d2010-10-24 15:11:22 +0000639
Guido van Rossum98297ee2007-11-06 21:34:58 +0000640.. exception:: BytesWarning
Georg Brandl116aa622007-08-15 14:28:22 +0000641
Guido van Rossum98297ee2007-11-06 21:34:58 +0000642 Base class for warnings related to :class:`bytes` and :class:`buffer`.
643
Georg Brandl08be72d2010-10-24 15:11:22 +0000644
645.. exception:: ResourceWarning
646
647 Base class for warnings related to resource usage.
648
649 .. versionadded:: 3.2
650
651
652
Alexandre Vassalottic22c6f22009-07-21 00:51:58 +0000653Exception hierarchy
654-------------------
Guido van Rossum98297ee2007-11-06 21:34:58 +0000655
656The class hierarchy for built-in exceptions is:
Georg Brandl116aa622007-08-15 14:28:22 +0000657
658.. literalinclude:: ../../Lib/test/exception_hierarchy.txt