Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | .. _bltin-exceptions: |
| 2 | |
| 3 | Built-in Exceptions |
| 4 | =================== |
| 5 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 6 | .. index:: |
| 7 | statement: try |
| 8 | statement: except |
| 9 | |
Georg Brandl | fbd1b22 | 2009-12-29 21:38:35 +0000 | [diff] [blame] | 10 | In 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 Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | clause that mentions a particular class, that clause also handles any exception |
| 13 | classes derived from that class (but not exception classes from which *it* is |
| 14 | derived). Two exception classes that are not related via subclassing are never |
| 15 | equivalent, even if they have the same name. |
| 16 | |
| 17 | .. index:: statement: raise |
| 18 | |
| 19 | The built-in exceptions listed below can be generated by the interpreter or |
| 20 | built-in functions. Except where mentioned, they have an "associated value" |
Georg Brandl | fb6fd5d | 2011-01-07 18:28:45 +0000 | [diff] [blame] | 21 | indicating the detailed cause of the error. This may be a string or a tuple of |
| 22 | several items of information (e.g., an error code and a string explaining the |
| 23 | code). The associated value is usually passed as arguments to the exception |
| 24 | class's constructor. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 25 | |
| 26 | User code can raise built-in exceptions. This can be used to test an exception |
| 27 | handler or to report an error condition "just like" the situation in which the |
| 28 | interpreter raises the same exception; but beware that there is nothing to |
| 29 | prevent user code from raising an inappropriate error. |
| 30 | |
| 31 | The built-in exception classes can be sub-classed to define new exceptions; |
| 32 | programmers are encouraged to at least derive new exceptions from the |
| 33 | :exc:`Exception` class and not :exc:`BaseException`. More information on |
| 34 | defining exceptions is available in the Python Tutorial under |
| 35 | :ref:`tut-userexceptions`. |
| 36 | |
Nick Coghlan | ab7bf21 | 2012-02-26 17:49:52 +1000 | [diff] [blame] | 37 | When raising (or re-raising) an exception in an :keyword:`except` clause |
| 38 | :attr:`__context__` is automatically set to the last exception caught; if the |
| 39 | new exception is not handled the traceback that is eventually displayed will |
| 40 | include the originating exception(s) and the final exception. |
| 41 | |
Nick Coghlan | 0eee97c | 2012-12-09 16:21:46 +1000 | [diff] [blame] | 42 | When raising a new exception (rather than using a bare ``raise`` to re-raise |
| 43 | the exception currently being handled), the implicit exception context can be |
| 44 | supplemented with an explicit cause by using :keyword:`from` with |
| 45 | :keyword:`raise`:: |
| 46 | |
| 47 | raise new_exc from original_exc |
| 48 | |
| 49 | The expression following :keyword:`from` must be an exception or ``None``. It |
| 50 | will be set as :attr:`__cause__` on the raised exception. Setting |
| 51 | :attr:`__cause__` also implicitly sets the :attr:`__suppress_context__` |
| 52 | attribute to ``True``, so that using ``raise new_exc from None`` |
| 53 | effectively replaces the old exception with the new one for display |
| 54 | purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`, while |
| 55 | leaving the old exception available in :attr:`__context__` for introspection |
| 56 | when debugging. |
Nick Coghlan | ab7bf21 | 2012-02-26 17:49:52 +1000 | [diff] [blame] | 57 | |
Nick Coghlan | 8e18fc8 | 2012-12-08 21:39:24 +1000 | [diff] [blame] | 58 | The default traceback display code shows these chained exceptions in |
| 59 | addition to the traceback for the exception itself. An explicitly chained |
| 60 | exception in :attr:`__cause__` is always shown when present. An implicitly |
| 61 | chained exception in :attr:`__context__` is shown only if :attr:`__cause__` |
Nick Coghlan | 0eee97c | 2012-12-09 16:21:46 +1000 | [diff] [blame] | 62 | is :const:`None` and :attr:`__suppress_context__` is false. |
Nick Coghlan | 8e18fc8 | 2012-12-08 21:39:24 +1000 | [diff] [blame] | 63 | |
| 64 | In either case, the exception itself is always shown after any chained |
| 65 | exceptions so that the final line of the traceback always shows the last |
| 66 | exception that was raised. |
Nick Coghlan | ab7bf21 | 2012-02-26 17:49:52 +1000 | [diff] [blame] | 67 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 68 | |
| 69 | Base classes |
| 70 | ------------ |
| 71 | |
Georg Brandl | fbd1b22 | 2009-12-29 21:38:35 +0000 | [diff] [blame] | 72 | The following exceptions are used mostly as base classes for other exceptions. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | .. exception:: BaseException |
| 75 | |
| 76 | The base class for all built-in exceptions. It is not meant to be directly |
Georg Brandl | fb6fd5d | 2011-01-07 18:28:45 +0000 | [diff] [blame] | 77 | inherited by user-defined classes (for that, use :exc:`Exception`). If |
Amaury Forgeot d'Arc | 3b1acf1 | 2011-11-22 19:34:08 +0100 | [diff] [blame] | 78 | :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 Brandl | fb6fd5d | 2011-01-07 18:28:45 +0000 | [diff] [blame] | 81 | |
| 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 Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | |
| 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 Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 107 | |
| 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 Brandl | 0bdfbfa | 2010-12-18 17:51:28 +0000 | [diff] [blame] | 115 | .. exception:: BufferError |
| 116 | |
| 117 | Raised when a :ref:`buffer <bufferobjects>` related operation cannot be |
| 118 | performed. |
| 119 | |
| 120 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | .. exception:: LookupError |
| 122 | |
Benjamin Peterson | fa0d703 | 2009-06-01 22:42:33 +0000 | [diff] [blame] | 123 | 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 Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 128 | Concrete exceptions |
| 129 | ------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 130 | |
Georg Brandl | fbd1b22 | 2009-12-29 21:38:35 +0000 | [diff] [blame] | 131 | The following exceptions are the exceptions that are usually raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 132 | |
| 133 | .. exception:: AssertionError |
| 134 | |
| 135 | .. index:: statement: assert |
| 136 | |
| 137 | Raised when an :keyword:`assert` statement fails. |
| 138 | |
| 139 | |
| 140 | .. exception:: AttributeError |
| 141 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 142 | 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 Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 145 | |
| 146 | |
| 147 | .. exception:: EOFError |
| 148 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 149 | 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 Brandl | 81ac1ce | 2007-08-31 17:17:17 +0000 | [diff] [blame] | 151 | :meth:`file.read` and :meth:`file.readline` methods return an empty string |
| 152 | when they hit EOF.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 153 | |
| 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 Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 159 | ``--with-fpectl`` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 160 | defined in the :file:`pyconfig.h` file. |
| 161 | |
| 162 | |
| 163 | .. exception:: GeneratorExit |
| 164 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 165 | 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 Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 168 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 169 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 170 | .. exception:: ImportError |
| 171 | |
| 172 | Raised when an :keyword:`import` statement fails to find the module definition |
| 173 | or when a ``from ... import`` fails to find a name that is to be imported. |
| 174 | |
Brett Cannon | 79ec55e | 2012-04-12 20:24:54 -0400 | [diff] [blame] | 175 | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 183 | |
| 184 | .. exception:: IndexError |
| 185 | |
Georg Brandl | 95817b3 | 2008-05-11 14:30:18 +0000 | [diff] [blame] | 186 | Raised when a sequence subscript is out of range. (Slice indices are |
| 187 | silently truncated to fall in the allowed range; if an index is not an |
| 188 | integer, :exc:`TypeError` is raised.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 189 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 190 | .. XXX xref to sequences |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 191 | |
| 192 | |
| 193 | .. exception:: KeyError |
| 194 | |
| 195 | Raised when a mapping (dictionary) key is not found in the set of existing keys. |
| 196 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 197 | .. XXX xref to mapping objects? |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 198 | |
| 199 | |
| 200 | .. exception:: KeyboardInterrupt |
| 201 | |
| 202 | Raised when the user hits the interrupt key (normally :kbd:`Control-C` or |
Georg Brandl | 81ac1ce | 2007-08-31 17:17:17 +0000 | [diff] [blame] | 203 | :kbd:`Delete`). During execution, a check for interrupts is made |
| 204 | regularly. The exception inherits from :exc:`BaseException` so as to not be |
| 205 | accidentally caught by code that catches :exc:`Exception` and thus prevent |
| 206 | the interpreter from exiting. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 207 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 208 | |
| 209 | .. exception:: MemoryError |
| 210 | |
| 211 | Raised when an operation runs out of memory but the situation may still be |
| 212 | rescued (by deleting some objects). The associated value is a string indicating |
| 213 | what kind of (internal) operation ran out of memory. Note that because of the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 214 | underlying memory management architecture (C's :c:func:`malloc` function), the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 215 | interpreter may not always be able to completely recover from this situation; it |
| 216 | nevertheless raises an exception so that a stack traceback can be printed, in |
| 217 | case a run-away program was the cause. |
| 218 | |
| 219 | |
| 220 | .. exception:: NameError |
| 221 | |
| 222 | Raised when a local or global name is not found. This applies only to |
| 223 | unqualified names. The associated value is an error message that includes the |
| 224 | name that could not be found. |
| 225 | |
| 226 | |
| 227 | .. exception:: NotImplementedError |
| 228 | |
| 229 | This exception is derived from :exc:`RuntimeError`. In user defined base |
| 230 | classes, abstract methods should raise this exception when they require derived |
| 231 | classes to override the method. |
| 232 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 233 | |
| 234 | .. exception:: OSError |
| 235 | |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 236 | .. index:: module: errno |
| 237 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 238 | This exception is raised when a system function returns a system-related |
| 239 | error, including I/O failures such as "file not found" or "disk full" |
| 240 | (not for illegal argument types or other incidental errors). Often a |
| 241 | subclass of :exc:`OSError` will actually be raised as described in |
| 242 | `OS exceptions`_ below. The :attr:`errno` attribute is a numeric error |
| 243 | code from the C variable :c:data:`errno`. |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 244 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 245 | Under Windows, the :attr:`winerror` attribute gives you the native |
| 246 | Windows error code. The :attr:`errno` attribute is then an approximate |
| 247 | translation, in POSIX terms, of that native error code. |
| 248 | |
| 249 | Under all platforms, the :attr:`strerror` attribute is the corresponding |
| 250 | error message as provided by the operating system (as formatted by the C |
| 251 | functions :c:func:`perror` under POSIX, and :c:func:`FormatMessage` |
| 252 | Windows). |
| 253 | |
| 254 | For exceptions that involve a file system path (such as :func:`open` or |
| 255 | :func:`os.unlink`), the exception instance will contain an additional |
| 256 | attribute, :attr:`filename`, which is the file name passed to the function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 257 | |
Antoine Pitrou | 195e702 | 2011-10-12 16:46:46 +0200 | [diff] [blame] | 258 | .. versionchanged:: 3.3 |
| 259 | :exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`, |
| 260 | :exc:`VMSError`, :exc:`socket.error`, :exc:`select.error` and |
| 261 | :exc:`mmap.error` have been merged into :exc:`OSError`. |
| 262 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | |
| 264 | .. exception:: OverflowError |
| 265 | |
| 266 | Raised when the result of an arithmetic operation is too large to be |
Georg Brandl | ba956ae | 2007-11-29 17:24:34 +0000 | [diff] [blame] | 267 | represented. This cannot occur for integers (which would rather raise |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 268 | :exc:`MemoryError` than give up). Because of the lack of standardization of |
| 269 | floating point exception handling in C, most floating point operations also |
Georg Brandl | 81ac1ce | 2007-08-31 17:17:17 +0000 | [diff] [blame] | 270 | aren't checked. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 271 | |
| 272 | |
| 273 | .. exception:: ReferenceError |
| 274 | |
| 275 | This exception is raised when a weak reference proxy, created by the |
| 276 | :func:`weakref.proxy` function, is used to access an attribute of the referent |
| 277 | after it has been garbage collected. For more information on weak references, |
| 278 | see the :mod:`weakref` module. |
| 279 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 280 | |
| 281 | .. exception:: RuntimeError |
| 282 | |
| 283 | Raised when an error is detected that doesn't fall in any of the other |
| 284 | categories. The associated value is a string indicating what precisely went |
| 285 | wrong. (This exception is mostly a relic from a previous version of the |
| 286 | interpreter; it is not used very much any more.) |
| 287 | |
| 288 | |
| 289 | .. exception:: StopIteration |
| 290 | |
Georg Brandl | c4a55fc | 2010-02-06 18:46:57 +0000 | [diff] [blame] | 291 | Raised by built-in function :func:`next` and an :term:`iterator`\'s |
Ezio Melotti | 1dd7c30 | 2012-10-12 13:45:38 +0300 | [diff] [blame] | 292 | :meth:`~iterator.__next__` method to signal that there are no further |
| 293 | items produced by the iterator. |
Nick Coghlan | 1f7ce62 | 2012-01-13 21:43:40 +1000 | [diff] [blame] | 294 | |
| 295 | The exception object has a single attribute :attr:`value`, which is |
| 296 | given as an argument when constructing the exception, and defaults |
| 297 | to :const:`None`. |
| 298 | |
| 299 | When a generator function returns, a new :exc:`StopIteration` instance is |
| 300 | raised, and the value returned by the function is used as the |
| 301 | :attr:`value` parameter to the constructor of the exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 302 | |
Nick Coghlan | 0ed8019 | 2012-01-14 14:43:24 +1000 | [diff] [blame] | 303 | .. versionchanged:: 3.3 |
| 304 | Added ``value`` attribute and the ability for generator functions to |
| 305 | use it to return a value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 306 | |
| 307 | .. exception:: SyntaxError |
| 308 | |
| 309 | Raised when the parser encounters a syntax error. This may occur in an |
| 310 | :keyword:`import` statement, in a call to the built-in functions :func:`exec` |
| 311 | or :func:`eval`, or when reading the initial script or standard input |
| 312 | (also interactively). |
| 313 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 314 | Instances of this class have attributes :attr:`filename`, :attr:`lineno`, |
| 315 | :attr:`offset` and :attr:`text` for easier access to the details. :func:`str` |
| 316 | of the exception instance returns only the message. |
| 317 | |
| 318 | |
Georg Brandl | 0bdfbfa | 2010-12-18 17:51:28 +0000 | [diff] [blame] | 319 | .. exception:: IndentationError |
| 320 | |
| 321 | Base class for syntax errors related to incorrect indentation. This is a |
| 322 | subclass of :exc:`SyntaxError`. |
| 323 | |
| 324 | |
| 325 | .. exception:: TabError |
| 326 | |
| 327 | Raised when indentation contains an inconsistent use of tabs and spaces. |
| 328 | This is a subclass of :exc:`IndentationError`. |
| 329 | |
| 330 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 331 | .. exception:: SystemError |
| 332 | |
| 333 | Raised when the interpreter finds an internal error, but the situation does not |
| 334 | look so serious to cause it to abandon all hope. The associated value is a |
| 335 | string indicating what went wrong (in low-level terms). |
| 336 | |
| 337 | You should report this to the author or maintainer of your Python interpreter. |
| 338 | Be sure to report the version of the Python interpreter (``sys.version``; it is |
| 339 | also printed at the start of an interactive Python session), the exact error |
| 340 | message (the exception's associated value) and if possible the source of the |
| 341 | program that triggered the error. |
| 342 | |
| 343 | |
| 344 | .. exception:: SystemExit |
| 345 | |
| 346 | This exception is raised by the :func:`sys.exit` function. When it is not |
| 347 | handled, the Python interpreter exits; no stack traceback is printed. If the |
Georg Brandl | 95817b3 | 2008-05-11 14:30:18 +0000 | [diff] [blame] | 348 | associated value is an integer, it specifies the system exit status (passed |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 349 | to C's :c:func:`exit` function); if it is ``None``, the exit status is zero; |
Georg Brandl | 95817b3 | 2008-05-11 14:30:18 +0000 | [diff] [blame] | 350 | if it has another type (such as a string), the object's value is printed and |
| 351 | the exit status is one. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 352 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 353 | Instances have an attribute :attr:`code` which is set to the proposed exit |
| 354 | status or error message (defaulting to ``None``). Also, this exception derives |
| 355 | directly from :exc:`BaseException` and not :exc:`Exception`, since it is not |
| 356 | technically an error. |
| 357 | |
| 358 | A call to :func:`sys.exit` is translated into an exception so that clean-up |
| 359 | handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be |
| 360 | executed, and so that a debugger can execute a script without running the risk |
| 361 | of losing control. The :func:`os._exit` function can be used if it is |
| 362 | absolutely positively necessary to exit immediately (for example, in the child |
| 363 | process after a call to :func:`fork`). |
| 364 | |
| 365 | The exception inherits from :exc:`BaseException` instead of :exc:`Exception` so |
| 366 | that it is not accidentally caught by code that catches :exc:`Exception`. This |
| 367 | allows the exception to properly propagate up and cause the interpreter to exit. |
| 368 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 369 | |
| 370 | .. exception:: TypeError |
| 371 | |
| 372 | Raised when an operation or function is applied to an object of inappropriate |
| 373 | type. The associated value is a string giving details about the type mismatch. |
| 374 | |
| 375 | |
| 376 | .. exception:: UnboundLocalError |
| 377 | |
| 378 | Raised when a reference is made to a local variable in a function or method, but |
| 379 | no value has been bound to that variable. This is a subclass of |
| 380 | :exc:`NameError`. |
| 381 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 382 | |
| 383 | .. exception:: UnicodeError |
| 384 | |
| 385 | Raised when a Unicode-related encoding or decoding error occurs. It is a |
| 386 | subclass of :exc:`ValueError`. |
| 387 | |
Benjamin Peterson | 78f7e3a | 2012-12-02 11:33:06 -0500 | [diff] [blame] | 388 | :exc:`UnicodeError` has attributes that describe the encoding or decoding |
| 389 | error. For example, ``err.object[err.start:err.end]`` gives the particular |
| 390 | invalid input that the codec failed on. |
| 391 | |
| 392 | .. attribute:: encoding |
| 393 | |
| 394 | The name of the encoding that raised the error. |
| 395 | |
| 396 | .. attribute:: reason |
| 397 | |
| 398 | A string describing the specific codec error. |
| 399 | |
| 400 | .. attribute:: object |
| 401 | |
| 402 | The object the codec was attempting to encode or decode. |
| 403 | |
| 404 | .. attribute:: start |
| 405 | |
| 406 | The first index of invalid data in :attr:`object`. |
| 407 | |
| 408 | .. attribute:: end |
| 409 | |
| 410 | The index after the last invalid data in :attr:`object`. |
| 411 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 412 | |
| 413 | .. exception:: UnicodeEncodeError |
| 414 | |
| 415 | Raised when a Unicode-related error occurs during encoding. It is a subclass of |
| 416 | :exc:`UnicodeError`. |
| 417 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 418 | |
| 419 | .. exception:: UnicodeDecodeError |
| 420 | |
| 421 | Raised when a Unicode-related error occurs during decoding. It is a subclass of |
| 422 | :exc:`UnicodeError`. |
| 423 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 424 | |
| 425 | .. exception:: UnicodeTranslateError |
| 426 | |
| 427 | Raised when a Unicode-related error occurs during translating. It is a subclass |
| 428 | of :exc:`UnicodeError`. |
| 429 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 430 | |
| 431 | .. exception:: ValueError |
| 432 | |
| 433 | Raised when a built-in operation or function receives an argument that has the |
| 434 | right type but an inappropriate value, and the situation is not described by a |
| 435 | more precise exception such as :exc:`IndexError`. |
| 436 | |
| 437 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 438 | .. exception:: ZeroDivisionError |
| 439 | |
| 440 | Raised when the second argument of a division or modulo operation is zero. The |
| 441 | associated value is a string indicating the type of the operands and the |
| 442 | operation. |
| 443 | |
Georg Brandl | fbd1b22 | 2009-12-29 21:38:35 +0000 | [diff] [blame] | 444 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 445 | The following exceptions are kept for compatibility with previous versions; |
| 446 | starting from Python 3.3, they are aliases of :exc:`OSError`. |
| 447 | |
| 448 | .. exception:: EnvironmentError |
| 449 | |
| 450 | .. exception:: IOError |
| 451 | |
| 452 | .. exception:: VMSError |
| 453 | |
| 454 | Only available on VMS. |
| 455 | |
| 456 | .. exception:: WindowsError |
| 457 | |
| 458 | Only available on Windows. |
| 459 | |
| 460 | |
| 461 | OS exceptions |
| 462 | ^^^^^^^^^^^^^ |
| 463 | |
| 464 | The following exceptions are subclasses of :exc:`OSError`, they get raised |
| 465 | depending on the system error code. |
| 466 | |
| 467 | .. exception:: BlockingIOError |
| 468 | |
| 469 | Raised when an operation would block on an object (e.g. socket) set |
| 470 | for non-blocking operation. |
| 471 | Corresponds to :c:data:`errno` ``EAGAIN``, ``EALREADY``, |
| 472 | ``EWOULDBLOCK`` and ``EINPROGRESS``. |
| 473 | |
Antoine Pitrou | f55011f | 2011-10-12 18:57:23 +0200 | [diff] [blame] | 474 | In addition to those of :exc:`OSError`, :exc:`BlockingIOError` can have |
| 475 | one more attribute: |
| 476 | |
| 477 | .. attribute:: characters_written |
| 478 | |
| 479 | An integer containing the number of characters written to the stream |
| 480 | before it blocked. This attribute is available when using the |
| 481 | buffered I/O classes from the :mod:`io` module. |
| 482 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 483 | .. exception:: ChildProcessError |
| 484 | |
| 485 | Raised when an operation on a child process failed. |
| 486 | Corresponds to :c:data:`errno` ``ECHILD``. |
| 487 | |
| 488 | .. exception:: ConnectionError |
| 489 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 490 | A base class for connection-related issues. |
| 491 | |
| 492 | Subclasses are :exc:`BrokenPipeError`, :exc:`ConnectionAbortedError`, |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 493 | :exc:`ConnectionRefusedError` and :exc:`ConnectionResetError`. |
| 494 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 495 | .. exception:: BrokenPipeError |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 496 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 497 | A subclass of :exc:`ConnectionError`, raised when trying to write on a |
| 498 | pipe while the other end has been closed, or trying to write on a socket |
| 499 | which has been shutdown for writing. |
| 500 | Corresponds to :c:data:`errno` ``EPIPE`` and ``ESHUTDOWN``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 501 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 502 | .. exception:: ConnectionAbortedError |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 503 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 504 | A subclass of :exc:`ConnectionError`, raised when a connection attempt |
| 505 | is aborted by the peer. |
| 506 | Corresponds to :c:data:`errno` ``ECONNABORTED``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 507 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 508 | .. exception:: ConnectionRefusedError |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 509 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 510 | A subclass of :exc:`ConnectionError`, raised when a connection attempt |
| 511 | is refused by the peer. |
| 512 | Corresponds to :c:data:`errno` ``ECONNREFUSED``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 513 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 514 | .. exception:: ConnectionResetError |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 515 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 516 | A subclass of :exc:`ConnectionError`, raised when a connection is |
| 517 | reset by the peer. |
| 518 | Corresponds to :c:data:`errno` ``ECONNRESET``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 519 | |
| 520 | .. exception:: FileExistsError |
| 521 | |
| 522 | Raised when trying to create a file or directory which already exists. |
| 523 | Corresponds to :c:data:`errno` ``EEXIST``. |
| 524 | |
| 525 | .. exception:: FileNotFoundError |
| 526 | |
| 527 | Raised when a file or directory is requested but doesn't exist. |
| 528 | Corresponds to :c:data:`errno` ``ENOENT``. |
| 529 | |
| 530 | .. exception:: InterruptedError |
| 531 | |
| 532 | Raised when a system call is interrupted by an incoming signal. |
Andrew Svetlov | 73a5a12 | 2012-12-05 11:12:14 +0200 | [diff] [blame] | 533 | Corresponds to :c:data:`errno` ``EINTR``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 534 | |
| 535 | .. exception:: IsADirectoryError |
| 536 | |
| 537 | Raised when a file operation (such as :func:`os.remove`) is requested |
| 538 | on a directory. |
| 539 | Corresponds to :c:data:`errno` ``EISDIR``. |
| 540 | |
| 541 | .. exception:: NotADirectoryError |
| 542 | |
| 543 | Raised when a directory operation (such as :func:`os.listdir`) is requested |
| 544 | on something which is not a directory. |
| 545 | Corresponds to :c:data:`errno` ``ENOTDIR``. |
| 546 | |
| 547 | .. exception:: PermissionError |
| 548 | |
| 549 | Raised when trying to run an operation without the adequate access |
| 550 | rights - for example filesystem permissions. |
| 551 | Corresponds to :c:data:`errno` ``EACCES`` and ``EPERM``. |
| 552 | |
| 553 | .. exception:: ProcessLookupError |
| 554 | |
| 555 | Raised when a given process doesn't exist. |
| 556 | Corresponds to :c:data:`errno` ``ESRCH``. |
| 557 | |
| 558 | .. exception:: TimeoutError |
| 559 | |
| 560 | Raised when a system function timed out at the system level. |
| 561 | Corresponds to :c:data:`errno` ``ETIMEDOUT``. |
| 562 | |
| 563 | .. versionadded:: 3.3 |
| 564 | All the above :exc:`OSError` subclasses were added. |
| 565 | |
| 566 | |
| 567 | .. seealso:: |
| 568 | |
| 569 | :pep:`3151` - Reworking the OS and IO exception hierarchy |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 570 | |
| 571 | |
| 572 | Warnings |
| 573 | -------- |
| 574 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 575 | The following exceptions are used as warning categories; see the :mod:`warnings` |
| 576 | module for more information. |
| 577 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 578 | .. exception:: Warning |
| 579 | |
| 580 | Base class for warning categories. |
| 581 | |
| 582 | |
| 583 | .. exception:: UserWarning |
| 584 | |
| 585 | Base class for warnings generated by user code. |
| 586 | |
| 587 | |
| 588 | .. exception:: DeprecationWarning |
| 589 | |
| 590 | Base class for warnings about deprecated features. |
| 591 | |
| 592 | |
| 593 | .. exception:: PendingDeprecationWarning |
| 594 | |
| 595 | Base class for warnings about features which will be deprecated in the future. |
| 596 | |
| 597 | |
| 598 | .. exception:: SyntaxWarning |
| 599 | |
| 600 | Base class for warnings about dubious syntax |
| 601 | |
| 602 | |
| 603 | .. exception:: RuntimeWarning |
| 604 | |
| 605 | Base class for warnings about dubious runtime behavior. |
| 606 | |
| 607 | |
| 608 | .. exception:: FutureWarning |
| 609 | |
| 610 | Base class for warnings about constructs that will change semantically in the |
| 611 | future. |
| 612 | |
| 613 | |
| 614 | .. exception:: ImportWarning |
| 615 | |
| 616 | Base class for warnings about probable mistakes in module imports. |
| 617 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 618 | |
| 619 | .. exception:: UnicodeWarning |
| 620 | |
| 621 | Base class for warnings related to Unicode. |
| 622 | |
Georg Brandl | 08be72d | 2010-10-24 15:11:22 +0000 | [diff] [blame] | 623 | |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 624 | .. exception:: BytesWarning |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 625 | |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 626 | Base class for warnings related to :class:`bytes` and :class:`buffer`. |
| 627 | |
Georg Brandl | 08be72d | 2010-10-24 15:11:22 +0000 | [diff] [blame] | 628 | |
| 629 | .. exception:: ResourceWarning |
| 630 | |
| 631 | Base class for warnings related to resource usage. |
| 632 | |
| 633 | .. versionadded:: 3.2 |
| 634 | |
| 635 | |
| 636 | |
Alexandre Vassalotti | c22c6f2 | 2009-07-21 00:51:58 +0000 | [diff] [blame] | 637 | Exception hierarchy |
| 638 | ------------------- |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 639 | |
| 640 | The class hierarchy for built-in exceptions is: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 641 | |
| 642 | .. literalinclude:: ../../Lib/test/exception_hierarchy.txt |