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 | |
Mark Dickinson | abf079d | 2014-04-14 11:20:12 -0400 | [diff] [blame] | 31 | The built-in exception classes can be subclassed to define new exceptions; |
| 32 | programmers are encouraged to derive new exceptions from the :exc:`Exception` |
| 33 | class or one of its subclasses, and not from :exc:`BaseException`. More |
| 34 | information on defining exceptions is available in the Python Tutorial under |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 35 | :ref:`tut-userexceptions`. |
| 36 | |
Georg Brandl | e4196d3 | 2014-10-31 09:41:46 +0100 | [diff] [blame] | 37 | When raising (or re-raising) an exception in an :keyword:`except` or |
| 38 | :keyword:`finally` clause |
Nick Coghlan | ab7bf21 | 2012-02-26 17:49:52 +1000 | [diff] [blame] | 39 | :attr:`__context__` is automatically set to the last exception caught; if the |
| 40 | new exception is not handled the traceback that is eventually displayed will |
| 41 | include the originating exception(s) and the final exception. |
| 42 | |
Nick Coghlan | 0eee97c | 2012-12-09 16:21:46 +1000 | [diff] [blame] | 43 | When raising a new exception (rather than using a bare ``raise`` to re-raise |
| 44 | the exception currently being handled), the implicit exception context can be |
| 45 | supplemented with an explicit cause by using :keyword:`from` with |
| 46 | :keyword:`raise`:: |
| 47 | |
| 48 | raise new_exc from original_exc |
| 49 | |
| 50 | The expression following :keyword:`from` must be an exception or ``None``. It |
| 51 | will be set as :attr:`__cause__` on the raised exception. Setting |
| 52 | :attr:`__cause__` also implicitly sets the :attr:`__suppress_context__` |
| 53 | attribute to ``True``, so that using ``raise new_exc from None`` |
| 54 | effectively replaces the old exception with the new one for display |
| 55 | purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`, while |
| 56 | leaving the old exception available in :attr:`__context__` for introspection |
| 57 | when debugging. |
Nick Coghlan | ab7bf21 | 2012-02-26 17:49:52 +1000 | [diff] [blame] | 58 | |
Nick Coghlan | 8e18fc8 | 2012-12-08 21:39:24 +1000 | [diff] [blame] | 59 | The default traceback display code shows these chained exceptions in |
| 60 | addition to the traceback for the exception itself. An explicitly chained |
| 61 | exception in :attr:`__cause__` is always shown when present. An implicitly |
| 62 | chained exception in :attr:`__context__` is shown only if :attr:`__cause__` |
Nick Coghlan | 0eee97c | 2012-12-09 16:21:46 +1000 | [diff] [blame] | 63 | is :const:`None` and :attr:`__suppress_context__` is false. |
Nick Coghlan | 8e18fc8 | 2012-12-08 21:39:24 +1000 | [diff] [blame] | 64 | |
| 65 | In either case, the exception itself is always shown after any chained |
| 66 | exceptions so that the final line of the traceback always shows the last |
| 67 | exception that was raised. |
Nick Coghlan | ab7bf21 | 2012-02-26 17:49:52 +1000 | [diff] [blame] | 68 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 69 | |
| 70 | Base classes |
| 71 | ------------ |
| 72 | |
Georg Brandl | fbd1b22 | 2009-12-29 21:38:35 +0000 | [diff] [blame] | 73 | The following exceptions are used mostly as base classes for other exceptions. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | .. exception:: BaseException |
| 76 | |
| 77 | 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] | 78 | 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] | 79 | :func:`str` is called on an instance of this class, the representation of |
| 80 | the argument(s) to the instance are returned, or the empty string when |
| 81 | there were no arguments. |
Georg Brandl | fb6fd5d | 2011-01-07 18:28:45 +0000 | [diff] [blame] | 82 | |
| 83 | .. attribute:: args |
| 84 | |
| 85 | The tuple of arguments given to the exception constructor. Some built-in |
Andrew Svetlov | 5898d4f | 2014-04-01 00:44:13 +0300 | [diff] [blame] | 86 | exceptions (like :exc:`OSError`) expect a certain number of arguments and |
Georg Brandl | fb6fd5d | 2011-01-07 18:28:45 +0000 | [diff] [blame] | 87 | assign a special meaning to the elements of this tuple, while others are |
| 88 | usually called only with a single string giving an error message. |
| 89 | |
| 90 | .. method:: with_traceback(tb) |
| 91 | |
| 92 | This method sets *tb* as the new traceback for the exception and returns |
| 93 | the exception object. It is usually used in exception handling code like |
| 94 | this:: |
| 95 | |
| 96 | try: |
| 97 | ... |
| 98 | except SomeException: |
| 99 | tb = sys.exc_info()[2] |
| 100 | raise OtherException(...).with_traceback(tb) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | |
| 103 | .. exception:: Exception |
| 104 | |
| 105 | All built-in, non-system-exiting exceptions are derived from this class. All |
| 106 | user-defined exceptions should also be derived from this class. |
| 107 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 108 | |
| 109 | .. exception:: ArithmeticError |
| 110 | |
| 111 | The base class for those built-in exceptions that are raised for various |
| 112 | arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`, |
| 113 | :exc:`FloatingPointError`. |
| 114 | |
| 115 | |
Georg Brandl | 0bdfbfa | 2010-12-18 17:51:28 +0000 | [diff] [blame] | 116 | .. exception:: BufferError |
| 117 | |
| 118 | Raised when a :ref:`buffer <bufferobjects>` related operation cannot be |
| 119 | performed. |
| 120 | |
| 121 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | .. exception:: LookupError |
| 123 | |
Benjamin Peterson | fa0d703 | 2009-06-01 22:42:33 +0000 | [diff] [blame] | 124 | The base class for the exceptions that are raised when a key or index used on |
| 125 | a mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`. This |
| 126 | can be raised directly by :func:`codecs.lookup`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 127 | |
| 128 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 129 | Concrete exceptions |
| 130 | ------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 131 | |
Georg Brandl | fbd1b22 | 2009-12-29 21:38:35 +0000 | [diff] [blame] | 132 | The following exceptions are the exceptions that are usually raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 133 | |
| 134 | .. exception:: AssertionError |
| 135 | |
| 136 | .. index:: statement: assert |
| 137 | |
| 138 | Raised when an :keyword:`assert` statement fails. |
| 139 | |
| 140 | |
| 141 | .. exception:: AttributeError |
| 142 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 143 | Raised when an attribute reference (see :ref:`attribute-references`) or |
| 144 | assignment fails. (When an object does not support attribute references or |
| 145 | attribute assignments at all, :exc:`TypeError` is raised.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 146 | |
| 147 | |
| 148 | .. exception:: EOFError |
| 149 | |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 150 | Raised when the :func:`input` function hits an end-of-file condition (EOF) |
| 151 | without reading any data. (N.B.: the :meth:`io.IOBase.read` and |
| 152 | :meth:`io.IOBase.readline` methods return an empty string 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 | |
Benjamin Peterson | 222ef82 | 2014-04-07 19:34:33 -0400 | [diff] [blame] | 165 | Raised when a :term:`generator`\'s :meth:`close` method is called. It |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 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 | |
Brett Cannon | 679ecb5 | 2013-07-04 17:51:50 -0400 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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. |
Larry Hastings | b082731 | 2014-02-09 22:05:19 -0800 | [diff] [blame] | 257 | For functions that involve two file system paths (such as |
| 258 | :func:`os.rename`), the exception instance will contain a second |
| 259 | :attr:`filename2` attribute corresponding to the second file name passed |
| 260 | to the function. |
| 261 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 262 | |
Antoine Pitrou | 195e702 | 2011-10-12 16:46:46 +0200 | [diff] [blame] | 263 | .. versionchanged:: 3.3 |
| 264 | :exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`, |
| 265 | :exc:`VMSError`, :exc:`socket.error`, :exc:`select.error` and |
| 266 | :exc:`mmap.error` have been merged into :exc:`OSError`. |
| 267 | |
Victor Stinner | 292c835 | 2012-10-30 02:17:38 +0100 | [diff] [blame] | 268 | .. versionchanged:: 3.4 |
Victor Stinner | 292c835 | 2012-10-30 02:17:38 +0100 | [diff] [blame] | 269 | The :attr:`filename` attribute is now the original file name passed to |
| 270 | the function, instead of the name encoded to or decoded from the |
Larry Hastings | b082731 | 2014-02-09 22:05:19 -0800 | [diff] [blame] | 271 | filesystem encoding. Also, the :attr:`filename2` attribute was added. |
Victor Stinner | 292c835 | 2012-10-30 02:17:38 +0100 | [diff] [blame] | 272 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 273 | |
| 274 | .. exception:: OverflowError |
| 275 | |
| 276 | 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] | 277 | represented. This cannot occur for integers (which would rather raise |
Terry Jan Reedy | b6d1f48 | 2014-06-16 03:31:00 -0400 | [diff] [blame] | 278 | :exc:`MemoryError` than give up). However, for historical reasons, |
| 279 | OverflowError is sometimes raised for integers that are outside a required |
| 280 | range. Because of the lack of standardization of floating point exception |
| 281 | handling in C, most floating point operations are not checked. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 282 | |
| 283 | |
| 284 | .. exception:: ReferenceError |
| 285 | |
| 286 | This exception is raised when a weak reference proxy, created by the |
| 287 | :func:`weakref.proxy` function, is used to access an attribute of the referent |
| 288 | after it has been garbage collected. For more information on weak references, |
| 289 | see the :mod:`weakref` module. |
| 290 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 291 | |
| 292 | .. exception:: RuntimeError |
| 293 | |
| 294 | Raised when an error is detected that doesn't fall in any of the other |
| 295 | categories. The associated value is a string indicating what precisely went |
Antoine Pitrou | 9527f16 | 2013-11-25 19:08:32 +0100 | [diff] [blame] | 296 | wrong. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 297 | |
| 298 | |
| 299 | .. exception:: StopIteration |
| 300 | |
Georg Brandl | c4a55fc | 2010-02-06 18:46:57 +0000 | [diff] [blame] | 301 | Raised by built-in function :func:`next` and an :term:`iterator`\'s |
Ezio Melotti | 1dd7c30 | 2012-10-12 13:45:38 +0300 | [diff] [blame] | 302 | :meth:`~iterator.__next__` method to signal that there are no further |
| 303 | items produced by the iterator. |
Nick Coghlan | 1f7ce62 | 2012-01-13 21:43:40 +1000 | [diff] [blame] | 304 | |
| 305 | The exception object has a single attribute :attr:`value`, which is |
| 306 | given as an argument when constructing the exception, and defaults |
| 307 | to :const:`None`. |
| 308 | |
| 309 | When a generator function returns, a new :exc:`StopIteration` instance is |
| 310 | raised, and the value returned by the function is used as the |
| 311 | :attr:`value` parameter to the constructor of the exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 312 | |
Nick Coghlan | 0ed8019 | 2012-01-14 14:43:24 +1000 | [diff] [blame] | 313 | .. versionchanged:: 3.3 |
| 314 | Added ``value`` attribute and the ability for generator functions to |
| 315 | use it to return a value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 316 | |
| 317 | .. exception:: SyntaxError |
| 318 | |
| 319 | Raised when the parser encounters a syntax error. This may occur in an |
| 320 | :keyword:`import` statement, in a call to the built-in functions :func:`exec` |
| 321 | or :func:`eval`, or when reading the initial script or standard input |
| 322 | (also interactively). |
| 323 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 324 | Instances of this class have attributes :attr:`filename`, :attr:`lineno`, |
| 325 | :attr:`offset` and :attr:`text` for easier access to the details. :func:`str` |
| 326 | of the exception instance returns only the message. |
| 327 | |
| 328 | |
Georg Brandl | 0bdfbfa | 2010-12-18 17:51:28 +0000 | [diff] [blame] | 329 | .. exception:: IndentationError |
| 330 | |
| 331 | Base class for syntax errors related to incorrect indentation. This is a |
| 332 | subclass of :exc:`SyntaxError`. |
| 333 | |
| 334 | |
| 335 | .. exception:: TabError |
| 336 | |
| 337 | Raised when indentation contains an inconsistent use of tabs and spaces. |
| 338 | This is a subclass of :exc:`IndentationError`. |
| 339 | |
| 340 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 341 | .. exception:: SystemError |
| 342 | |
| 343 | Raised when the interpreter finds an internal error, but the situation does not |
| 344 | look so serious to cause it to abandon all hope. The associated value is a |
| 345 | string indicating what went wrong (in low-level terms). |
| 346 | |
| 347 | You should report this to the author or maintainer of your Python interpreter. |
| 348 | Be sure to report the version of the Python interpreter (``sys.version``; it is |
| 349 | also printed at the start of an interactive Python session), the exact error |
| 350 | message (the exception's associated value) and if possible the source of the |
| 351 | program that triggered the error. |
| 352 | |
| 353 | |
| 354 | .. exception:: SystemExit |
| 355 | |
| 356 | This exception is raised by the :func:`sys.exit` function. When it is not |
| 357 | handled, the Python interpreter exits; no stack traceback is printed. If the |
Georg Brandl | 95817b3 | 2008-05-11 14:30:18 +0000 | [diff] [blame] | 358 | associated value is an integer, it specifies the system exit status (passed |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 359 | 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] | 360 | if it has another type (such as a string), the object's value is printed and |
| 361 | the exit status is one. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 362 | |
Georg Brandl | f24c141 | 2013-10-08 21:43:39 +0200 | [diff] [blame] | 363 | Instances have an attribute :attr:`!code` which is set to the proposed exit |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 364 | status or error message (defaulting to ``None``). Also, this exception derives |
| 365 | directly from :exc:`BaseException` and not :exc:`Exception`, since it is not |
| 366 | technically an error. |
| 367 | |
| 368 | A call to :func:`sys.exit` is translated into an exception so that clean-up |
| 369 | handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be |
| 370 | executed, and so that a debugger can execute a script without running the risk |
| 371 | of losing control. The :func:`os._exit` function can be used if it is |
| 372 | absolutely positively necessary to exit immediately (for example, in the child |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 373 | process after a call to :func:`os.fork`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 374 | |
| 375 | The exception inherits from :exc:`BaseException` instead of :exc:`Exception` so |
| 376 | that it is not accidentally caught by code that catches :exc:`Exception`. This |
| 377 | allows the exception to properly propagate up and cause the interpreter to exit. |
| 378 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 379 | |
| 380 | .. exception:: TypeError |
| 381 | |
| 382 | Raised when an operation or function is applied to an object of inappropriate |
| 383 | type. The associated value is a string giving details about the type mismatch. |
| 384 | |
| 385 | |
| 386 | .. exception:: UnboundLocalError |
| 387 | |
| 388 | Raised when a reference is made to a local variable in a function or method, but |
| 389 | no value has been bound to that variable. This is a subclass of |
| 390 | :exc:`NameError`. |
| 391 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 392 | |
| 393 | .. exception:: UnicodeError |
| 394 | |
| 395 | Raised when a Unicode-related encoding or decoding error occurs. It is a |
| 396 | subclass of :exc:`ValueError`. |
| 397 | |
Benjamin Peterson | 78f7e3a | 2012-12-02 11:33:06 -0500 | [diff] [blame] | 398 | :exc:`UnicodeError` has attributes that describe the encoding or decoding |
| 399 | error. For example, ``err.object[err.start:err.end]`` gives the particular |
| 400 | invalid input that the codec failed on. |
| 401 | |
| 402 | .. attribute:: encoding |
| 403 | |
| 404 | The name of the encoding that raised the error. |
| 405 | |
| 406 | .. attribute:: reason |
| 407 | |
| 408 | A string describing the specific codec error. |
| 409 | |
| 410 | .. attribute:: object |
| 411 | |
| 412 | The object the codec was attempting to encode or decode. |
| 413 | |
| 414 | .. attribute:: start |
| 415 | |
| 416 | The first index of invalid data in :attr:`object`. |
| 417 | |
| 418 | .. attribute:: end |
| 419 | |
| 420 | The index after the last invalid data in :attr:`object`. |
| 421 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 422 | |
| 423 | .. exception:: UnicodeEncodeError |
| 424 | |
| 425 | Raised when a Unicode-related error occurs during encoding. It is a subclass of |
| 426 | :exc:`UnicodeError`. |
| 427 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 428 | |
| 429 | .. exception:: UnicodeDecodeError |
| 430 | |
| 431 | Raised when a Unicode-related error occurs during decoding. It is a subclass of |
| 432 | :exc:`UnicodeError`. |
| 433 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 434 | |
| 435 | .. exception:: UnicodeTranslateError |
| 436 | |
| 437 | Raised when a Unicode-related error occurs during translating. It is a subclass |
| 438 | of :exc:`UnicodeError`. |
| 439 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 440 | |
| 441 | .. exception:: ValueError |
| 442 | |
| 443 | Raised when a built-in operation or function receives an argument that has the |
| 444 | right type but an inappropriate value, and the situation is not described by a |
| 445 | more precise exception such as :exc:`IndexError`. |
| 446 | |
| 447 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 448 | .. exception:: ZeroDivisionError |
| 449 | |
| 450 | Raised when the second argument of a division or modulo operation is zero. The |
| 451 | associated value is a string indicating the type of the operands and the |
| 452 | operation. |
| 453 | |
Georg Brandl | fbd1b22 | 2009-12-29 21:38:35 +0000 | [diff] [blame] | 454 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 455 | The following exceptions are kept for compatibility with previous versions; |
| 456 | starting from Python 3.3, they are aliases of :exc:`OSError`. |
| 457 | |
| 458 | .. exception:: EnvironmentError |
| 459 | |
| 460 | .. exception:: IOError |
| 461 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 462 | .. exception:: WindowsError |
| 463 | |
| 464 | Only available on Windows. |
| 465 | |
| 466 | |
| 467 | OS exceptions |
| 468 | ^^^^^^^^^^^^^ |
| 469 | |
| 470 | The following exceptions are subclasses of :exc:`OSError`, they get raised |
| 471 | depending on the system error code. |
| 472 | |
| 473 | .. exception:: BlockingIOError |
| 474 | |
| 475 | Raised when an operation would block on an object (e.g. socket) set |
| 476 | for non-blocking operation. |
| 477 | Corresponds to :c:data:`errno` ``EAGAIN``, ``EALREADY``, |
| 478 | ``EWOULDBLOCK`` and ``EINPROGRESS``. |
| 479 | |
Antoine Pitrou | f55011f | 2011-10-12 18:57:23 +0200 | [diff] [blame] | 480 | In addition to those of :exc:`OSError`, :exc:`BlockingIOError` can have |
| 481 | one more attribute: |
| 482 | |
| 483 | .. attribute:: characters_written |
| 484 | |
| 485 | An integer containing the number of characters written to the stream |
| 486 | before it blocked. This attribute is available when using the |
| 487 | buffered I/O classes from the :mod:`io` module. |
| 488 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 489 | .. exception:: ChildProcessError |
| 490 | |
| 491 | Raised when an operation on a child process failed. |
| 492 | Corresponds to :c:data:`errno` ``ECHILD``. |
| 493 | |
| 494 | .. exception:: ConnectionError |
| 495 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 496 | A base class for connection-related issues. |
| 497 | |
| 498 | Subclasses are :exc:`BrokenPipeError`, :exc:`ConnectionAbortedError`, |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 499 | :exc:`ConnectionRefusedError` and :exc:`ConnectionResetError`. |
| 500 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 501 | .. exception:: BrokenPipeError |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 502 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 503 | A subclass of :exc:`ConnectionError`, raised when trying to write on a |
| 504 | pipe while the other end has been closed, or trying to write on a socket |
| 505 | which has been shutdown for writing. |
| 506 | Corresponds to :c:data:`errno` ``EPIPE`` and ``ESHUTDOWN``. |
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:: ConnectionAbortedError |
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 aborted by the peer. |
| 512 | Corresponds to :c:data:`errno` ``ECONNABORTED``. |
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:: ConnectionRefusedError |
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 attempt |
| 517 | is refused by the peer. |
| 518 | Corresponds to :c:data:`errno` ``ECONNREFUSED``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 519 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 520 | .. exception:: ConnectionResetError |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 521 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 522 | A subclass of :exc:`ConnectionError`, raised when a connection is |
| 523 | reset by the peer. |
| 524 | Corresponds to :c:data:`errno` ``ECONNRESET``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 525 | |
| 526 | .. exception:: FileExistsError |
| 527 | |
| 528 | Raised when trying to create a file or directory which already exists. |
| 529 | Corresponds to :c:data:`errno` ``EEXIST``. |
| 530 | |
| 531 | .. exception:: FileNotFoundError |
| 532 | |
| 533 | Raised when a file or directory is requested but doesn't exist. |
| 534 | Corresponds to :c:data:`errno` ``ENOENT``. |
| 535 | |
| 536 | .. exception:: InterruptedError |
| 537 | |
| 538 | Raised when a system call is interrupted by an incoming signal. |
Andrew Svetlov | 73a5a12 | 2012-12-05 11:12:14 +0200 | [diff] [blame] | 539 | Corresponds to :c:data:`errno` ``EINTR``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 540 | |
| 541 | .. exception:: IsADirectoryError |
| 542 | |
| 543 | Raised when a file operation (such as :func:`os.remove`) is requested |
| 544 | on a directory. |
| 545 | Corresponds to :c:data:`errno` ``EISDIR``. |
| 546 | |
| 547 | .. exception:: NotADirectoryError |
| 548 | |
| 549 | Raised when a directory operation (such as :func:`os.listdir`) is requested |
| 550 | on something which is not a directory. |
| 551 | Corresponds to :c:data:`errno` ``ENOTDIR``. |
| 552 | |
| 553 | .. exception:: PermissionError |
| 554 | |
| 555 | Raised when trying to run an operation without the adequate access |
| 556 | rights - for example filesystem permissions. |
| 557 | Corresponds to :c:data:`errno` ``EACCES`` and ``EPERM``. |
| 558 | |
| 559 | .. exception:: ProcessLookupError |
| 560 | |
| 561 | Raised when a given process doesn't exist. |
| 562 | Corresponds to :c:data:`errno` ``ESRCH``. |
| 563 | |
| 564 | .. exception:: TimeoutError |
| 565 | |
| 566 | Raised when a system function timed out at the system level. |
| 567 | Corresponds to :c:data:`errno` ``ETIMEDOUT``. |
| 568 | |
| 569 | .. versionadded:: 3.3 |
| 570 | All the above :exc:`OSError` subclasses were added. |
| 571 | |
| 572 | |
| 573 | .. seealso:: |
| 574 | |
| 575 | :pep:`3151` - Reworking the OS and IO exception hierarchy |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 576 | |
| 577 | |
| 578 | Warnings |
| 579 | -------- |
| 580 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 581 | The following exceptions are used as warning categories; see the :mod:`warnings` |
| 582 | module for more information. |
| 583 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 584 | .. exception:: Warning |
| 585 | |
| 586 | Base class for warning categories. |
| 587 | |
| 588 | |
| 589 | .. exception:: UserWarning |
| 590 | |
| 591 | Base class for warnings generated by user code. |
| 592 | |
| 593 | |
| 594 | .. exception:: DeprecationWarning |
| 595 | |
| 596 | Base class for warnings about deprecated features. |
| 597 | |
| 598 | |
| 599 | .. exception:: PendingDeprecationWarning |
| 600 | |
| 601 | Base class for warnings about features which will be deprecated in the future. |
| 602 | |
| 603 | |
| 604 | .. exception:: SyntaxWarning |
| 605 | |
| 606 | Base class for warnings about dubious syntax |
| 607 | |
| 608 | |
| 609 | .. exception:: RuntimeWarning |
| 610 | |
| 611 | Base class for warnings about dubious runtime behavior. |
| 612 | |
| 613 | |
| 614 | .. exception:: FutureWarning |
| 615 | |
| 616 | Base class for warnings about constructs that will change semantically in the |
| 617 | future. |
| 618 | |
| 619 | |
| 620 | .. exception:: ImportWarning |
| 621 | |
| 622 | Base class for warnings about probable mistakes in module imports. |
| 623 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 624 | |
| 625 | .. exception:: UnicodeWarning |
| 626 | |
| 627 | Base class for warnings related to Unicode. |
| 628 | |
Georg Brandl | 08be72d | 2010-10-24 15:11:22 +0000 | [diff] [blame] | 629 | |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 630 | .. exception:: BytesWarning |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 631 | |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 632 | Base class for warnings related to :class:`bytes` and :class:`bytearray`. |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 633 | |
Georg Brandl | 08be72d | 2010-10-24 15:11:22 +0000 | [diff] [blame] | 634 | |
| 635 | .. exception:: ResourceWarning |
| 636 | |
| 637 | Base class for warnings related to resource usage. |
| 638 | |
| 639 | .. versionadded:: 3.2 |
| 640 | |
| 641 | |
| 642 | |
Alexandre Vassalotti | c22c6f2 | 2009-07-21 00:51:58 +0000 | [diff] [blame] | 643 | Exception hierarchy |
| 644 | ------------------- |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 645 | |
| 646 | The class hierarchy for built-in exceptions is: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 647 | |
| 648 | .. literalinclude:: ../../Lib/test/exception_hierarchy.txt |