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 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 165 | Raised when a :term:`generator` or :term:`coroutine` is closed; |
| 166 | see :meth:`generator.close` and :meth:`coroutine.close`. It |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 167 | directly inherits from :exc:`BaseException` instead of :exc:`Exception` since |
| 168 | it is technically not an error. |
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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 171 | .. exception:: ImportError |
| 172 | |
Brett Cannon | 679ecb5 | 2013-07-04 17:51:50 -0400 | [diff] [blame] | 173 | Raised when an :keyword:`import` statement fails to find the module definition |
| 174 | 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] | 175 | |
Brett Cannon | 79ec55e | 2012-04-12 20:24:54 -0400 | [diff] [blame] | 176 | The :attr:`name` and :attr:`path` attributes can be set using keyword-only |
| 177 | arguments to the constructor. When set they represent the name of the module |
| 178 | that was attempted to be imported and the path to any file which triggered |
| 179 | the exception, respectively. |
| 180 | |
| 181 | .. versionchanged:: 3.3 |
| 182 | Added the :attr:`name` and :attr:`path` attributes. |
| 183 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 184 | |
| 185 | .. exception:: IndexError |
| 186 | |
Georg Brandl | 95817b3 | 2008-05-11 14:30:18 +0000 | [diff] [blame] | 187 | Raised when a sequence subscript is out of range. (Slice indices are |
| 188 | silently truncated to fall in the allowed range; if an index is not an |
| 189 | integer, :exc:`TypeError` is raised.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 190 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 191 | .. XXX xref to sequences |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 192 | |
| 193 | |
| 194 | .. exception:: KeyError |
| 195 | |
| 196 | Raised when a mapping (dictionary) key is not found in the set of existing keys. |
| 197 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 198 | .. XXX xref to mapping objects? |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 199 | |
| 200 | |
| 201 | .. exception:: KeyboardInterrupt |
| 202 | |
| 203 | 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] | 204 | :kbd:`Delete`). During execution, a check for interrupts is made |
| 205 | regularly. The exception inherits from :exc:`BaseException` so as to not be |
| 206 | accidentally caught by code that catches :exc:`Exception` and thus prevent |
| 207 | the interpreter from exiting. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 208 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 209 | |
| 210 | .. exception:: MemoryError |
| 211 | |
| 212 | Raised when an operation runs out of memory but the situation may still be |
| 213 | rescued (by deleting some objects). The associated value is a string indicating |
| 214 | 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] | 215 | underlying memory management architecture (C's :c:func:`malloc` function), the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 216 | interpreter may not always be able to completely recover from this situation; it |
| 217 | nevertheless raises an exception so that a stack traceback can be printed, in |
| 218 | case a run-away program was the cause. |
| 219 | |
| 220 | |
| 221 | .. exception:: NameError |
| 222 | |
| 223 | Raised when a local or global name is not found. This applies only to |
| 224 | unqualified names. The associated value is an error message that includes the |
| 225 | name that could not be found. |
| 226 | |
| 227 | |
| 228 | .. exception:: NotImplementedError |
| 229 | |
| 230 | This exception is derived from :exc:`RuntimeError`. In user defined base |
| 231 | classes, abstract methods should raise this exception when they require derived |
| 232 | classes to override the method. |
| 233 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 234 | |
| 235 | .. exception:: OSError |
| 236 | |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 237 | .. index:: module: errno |
| 238 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 239 | This exception is raised when a system function returns a system-related |
| 240 | error, including I/O failures such as "file not found" or "disk full" |
| 241 | (not for illegal argument types or other incidental errors). Often a |
| 242 | subclass of :exc:`OSError` will actually be raised as described in |
| 243 | `OS exceptions`_ below. The :attr:`errno` attribute is a numeric error |
| 244 | code from the C variable :c:data:`errno`. |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 245 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 246 | Under Windows, the :attr:`winerror` attribute gives you the native |
| 247 | Windows error code. The :attr:`errno` attribute is then an approximate |
| 248 | translation, in POSIX terms, of that native error code. |
| 249 | |
| 250 | Under all platforms, the :attr:`strerror` attribute is the corresponding |
| 251 | error message as provided by the operating system (as formatted by the C |
| 252 | functions :c:func:`perror` under POSIX, and :c:func:`FormatMessage` |
| 253 | Windows). |
| 254 | |
| 255 | For exceptions that involve a file system path (such as :func:`open` or |
| 256 | :func:`os.unlink`), the exception instance will contain an additional |
| 257 | attribute, :attr:`filename`, which is the file name passed to the function. |
Larry Hastings | b082731 | 2014-02-09 22:05:19 -0800 | [diff] [blame] | 258 | For functions that involve two file system paths (such as |
| 259 | :func:`os.rename`), the exception instance will contain a second |
| 260 | :attr:`filename2` attribute corresponding to the second file name passed |
| 261 | to the function. |
| 262 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | |
Antoine Pitrou | 195e702 | 2011-10-12 16:46:46 +0200 | [diff] [blame] | 264 | .. versionchanged:: 3.3 |
| 265 | :exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`, |
| 266 | :exc:`VMSError`, :exc:`socket.error`, :exc:`select.error` and |
| 267 | :exc:`mmap.error` have been merged into :exc:`OSError`. |
| 268 | |
Victor Stinner | 292c835 | 2012-10-30 02:17:38 +0100 | [diff] [blame] | 269 | .. versionchanged:: 3.4 |
Victor Stinner | 292c835 | 2012-10-30 02:17:38 +0100 | [diff] [blame] | 270 | The :attr:`filename` attribute is now the original file name passed to |
| 271 | the function, instead of the name encoded to or decoded from the |
Larry Hastings | b082731 | 2014-02-09 22:05:19 -0800 | [diff] [blame] | 272 | filesystem encoding. Also, the :attr:`filename2` attribute was added. |
Victor Stinner | 292c835 | 2012-10-30 02:17:38 +0100 | [diff] [blame] | 273 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 274 | |
| 275 | .. exception:: OverflowError |
| 276 | |
| 277 | 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] | 278 | represented. This cannot occur for integers (which would rather raise |
Terry Jan Reedy | b6d1f48 | 2014-06-16 03:31:00 -0400 | [diff] [blame] | 279 | :exc:`MemoryError` than give up). However, for historical reasons, |
| 280 | OverflowError is sometimes raised for integers that are outside a required |
| 281 | range. Because of the lack of standardization of floating point exception |
| 282 | handling in C, most floating point operations are not checked. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 283 | |
| 284 | |
Yury Selivanov | f488fb4 | 2015-07-03 01:04:23 -0400 | [diff] [blame] | 285 | .. exception:: RecursionError |
| 286 | |
| 287 | This exception is derived from :exc:`RuntimeError`. It is raised when the |
| 288 | interpreter detects that the maximum recursion depth (see |
| 289 | :func:`sys.getrecursionlimit`) is exceeded. |
| 290 | |
| 291 | .. versionadded:: 3.5 |
| 292 | Previously, a plain :exc:`RuntimeError` was raised. |
| 293 | |
| 294 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 295 | .. exception:: ReferenceError |
| 296 | |
| 297 | This exception is raised when a weak reference proxy, created by the |
| 298 | :func:`weakref.proxy` function, is used to access an attribute of the referent |
| 299 | after it has been garbage collected. For more information on weak references, |
| 300 | see the :mod:`weakref` module. |
| 301 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 302 | |
| 303 | .. exception:: RuntimeError |
| 304 | |
| 305 | Raised when an error is detected that doesn't fall in any of the other |
| 306 | categories. The associated value is a string indicating what precisely went |
Antoine Pitrou | 9527f16 | 2013-11-25 19:08:32 +0100 | [diff] [blame] | 307 | wrong. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 308 | |
| 309 | |
| 310 | .. exception:: StopIteration |
| 311 | |
Georg Brandl | c4a55fc | 2010-02-06 18:46:57 +0000 | [diff] [blame] | 312 | Raised by built-in function :func:`next` and an :term:`iterator`\'s |
Ezio Melotti | 1dd7c30 | 2012-10-12 13:45:38 +0300 | [diff] [blame] | 313 | :meth:`~iterator.__next__` method to signal that there are no further |
| 314 | items produced by the iterator. |
Nick Coghlan | 1f7ce62 | 2012-01-13 21:43:40 +1000 | [diff] [blame] | 315 | |
| 316 | The exception object has a single attribute :attr:`value`, which is |
| 317 | given as an argument when constructing the exception, and defaults |
| 318 | to :const:`None`. |
| 319 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 320 | When a :term:`generator` or :term:`coroutine` function |
| 321 | returns, a new :exc:`StopIteration` instance is |
Nick Coghlan | 1f7ce62 | 2012-01-13 21:43:40 +1000 | [diff] [blame] | 322 | raised, and the value returned by the function is used as the |
| 323 | :attr:`value` parameter to the constructor of the exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 324 | |
Yury Selivanov | 8170e8c | 2015-05-09 11:44:30 -0400 | [diff] [blame] | 325 | If a generator function defined in the presence of a ``from __future__ |
| 326 | import generator_stop`` directive raises :exc:`StopIteration`, it will be |
| 327 | converted into a :exc:`RuntimeError` (retaining the :exc:`StopIteration` |
| 328 | as the new exception's cause). |
| 329 | |
Nick Coghlan | 0ed8019 | 2012-01-14 14:43:24 +1000 | [diff] [blame] | 330 | .. versionchanged:: 3.3 |
| 331 | Added ``value`` attribute and the ability for generator functions to |
| 332 | use it to return a value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 333 | |
Yury Selivanov | 8170e8c | 2015-05-09 11:44:30 -0400 | [diff] [blame] | 334 | .. versionchanged:: 3.5 |
| 335 | Introduced the RuntimeError transformation. |
| 336 | |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 337 | .. exception:: StopAsyncIteration |
| 338 | |
| 339 | Must be raised by :meth:`__anext__` method of an |
| 340 | :term:`asynchronous iterator` object to stop the iteration. |
| 341 | |
| 342 | .. versionadded:: 3.5 |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 343 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 344 | .. exception:: SyntaxError |
| 345 | |
| 346 | Raised when the parser encounters a syntax error. This may occur in an |
| 347 | :keyword:`import` statement, in a call to the built-in functions :func:`exec` |
| 348 | or :func:`eval`, or when reading the initial script or standard input |
| 349 | (also interactively). |
| 350 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 351 | Instances of this class have attributes :attr:`filename`, :attr:`lineno`, |
| 352 | :attr:`offset` and :attr:`text` for easier access to the details. :func:`str` |
| 353 | of the exception instance returns only the message. |
| 354 | |
| 355 | |
Georg Brandl | 0bdfbfa | 2010-12-18 17:51:28 +0000 | [diff] [blame] | 356 | .. exception:: IndentationError |
| 357 | |
| 358 | Base class for syntax errors related to incorrect indentation. This is a |
| 359 | subclass of :exc:`SyntaxError`. |
| 360 | |
| 361 | |
| 362 | .. exception:: TabError |
| 363 | |
| 364 | Raised when indentation contains an inconsistent use of tabs and spaces. |
| 365 | This is a subclass of :exc:`IndentationError`. |
| 366 | |
| 367 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 368 | .. exception:: SystemError |
| 369 | |
| 370 | Raised when the interpreter finds an internal error, but the situation does not |
| 371 | look so serious to cause it to abandon all hope. The associated value is a |
| 372 | string indicating what went wrong (in low-level terms). |
| 373 | |
| 374 | You should report this to the author or maintainer of your Python interpreter. |
| 375 | Be sure to report the version of the Python interpreter (``sys.version``; it is |
| 376 | also printed at the start of an interactive Python session), the exact error |
| 377 | message (the exception's associated value) and if possible the source of the |
| 378 | program that triggered the error. |
| 379 | |
| 380 | |
| 381 | .. exception:: SystemExit |
| 382 | |
Berker Peksag | 77a6b20 | 2015-03-10 14:47:15 +0200 | [diff] [blame] | 383 | This exception is raised by the :func:`sys.exit` function. It inherits from |
| 384 | :exc:`BaseException` instead of :exc:`Exception` so that it is not accidentally |
| 385 | caught by code that catches :exc:`Exception`. This allows the exception to |
| 386 | properly propagate up and cause the interpreter to exit. When it is not |
| 387 | handled, the Python interpreter exits; no stack traceback is printed. The |
| 388 | constructor accepts the same optional argument passed to :func:`sys.exit`. |
| 389 | If the value is an integer, it specifies the system exit status (passed to |
| 390 | C's :c:func:`exit` function); if it is ``None``, the exit status is zero; if |
| 391 | it has another type (such as a string), the object's value is printed and |
Georg Brandl | 95817b3 | 2008-05-11 14:30:18 +0000 | [diff] [blame] | 392 | the exit status is one. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 393 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 394 | A call to :func:`sys.exit` is translated into an exception so that clean-up |
| 395 | handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be |
| 396 | executed, and so that a debugger can execute a script without running the risk |
| 397 | of losing control. The :func:`os._exit` function can be used if it is |
| 398 | absolutely positively necessary to exit immediately (for example, in the child |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 399 | process after a call to :func:`os.fork`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 400 | |
Berker Peksag | 77a6b20 | 2015-03-10 14:47:15 +0200 | [diff] [blame] | 401 | .. attribute:: code |
| 402 | |
| 403 | The exit status or error message that is passed to the constructor. |
| 404 | (Defaults to ``None``.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 405 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 406 | |
| 407 | .. exception:: TypeError |
| 408 | |
| 409 | Raised when an operation or function is applied to an object of inappropriate |
| 410 | type. The associated value is a string giving details about the type mismatch. |
| 411 | |
| 412 | |
| 413 | .. exception:: UnboundLocalError |
| 414 | |
| 415 | Raised when a reference is made to a local variable in a function or method, but |
| 416 | no value has been bound to that variable. This is a subclass of |
| 417 | :exc:`NameError`. |
| 418 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 419 | |
| 420 | .. exception:: UnicodeError |
| 421 | |
| 422 | Raised when a Unicode-related encoding or decoding error occurs. It is a |
| 423 | subclass of :exc:`ValueError`. |
| 424 | |
Benjamin Peterson | 78f7e3a | 2012-12-02 11:33:06 -0500 | [diff] [blame] | 425 | :exc:`UnicodeError` has attributes that describe the encoding or decoding |
| 426 | error. For example, ``err.object[err.start:err.end]`` gives the particular |
| 427 | invalid input that the codec failed on. |
| 428 | |
| 429 | .. attribute:: encoding |
| 430 | |
| 431 | The name of the encoding that raised the error. |
| 432 | |
| 433 | .. attribute:: reason |
| 434 | |
| 435 | A string describing the specific codec error. |
| 436 | |
| 437 | .. attribute:: object |
| 438 | |
| 439 | The object the codec was attempting to encode or decode. |
| 440 | |
| 441 | .. attribute:: start |
| 442 | |
| 443 | The first index of invalid data in :attr:`object`. |
| 444 | |
| 445 | .. attribute:: end |
| 446 | |
| 447 | The index after the last invalid data in :attr:`object`. |
| 448 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 449 | |
| 450 | .. exception:: UnicodeEncodeError |
| 451 | |
| 452 | Raised when a Unicode-related error occurs during encoding. It is a subclass of |
| 453 | :exc:`UnicodeError`. |
| 454 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 455 | |
| 456 | .. exception:: UnicodeDecodeError |
| 457 | |
| 458 | Raised when a Unicode-related error occurs during decoding. It is a subclass of |
| 459 | :exc:`UnicodeError`. |
| 460 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 461 | |
| 462 | .. exception:: UnicodeTranslateError |
| 463 | |
| 464 | Raised when a Unicode-related error occurs during translating. It is a subclass |
| 465 | of :exc:`UnicodeError`. |
| 466 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 467 | |
| 468 | .. exception:: ValueError |
| 469 | |
| 470 | Raised when a built-in operation or function receives an argument that has the |
| 471 | right type but an inappropriate value, and the situation is not described by a |
| 472 | more precise exception such as :exc:`IndexError`. |
| 473 | |
| 474 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 475 | .. exception:: ZeroDivisionError |
| 476 | |
| 477 | Raised when the second argument of a division or modulo operation is zero. The |
| 478 | associated value is a string indicating the type of the operands and the |
| 479 | operation. |
| 480 | |
Georg Brandl | fbd1b22 | 2009-12-29 21:38:35 +0000 | [diff] [blame] | 481 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 482 | The following exceptions are kept for compatibility with previous versions; |
| 483 | starting from Python 3.3, they are aliases of :exc:`OSError`. |
| 484 | |
| 485 | .. exception:: EnvironmentError |
| 486 | |
| 487 | .. exception:: IOError |
| 488 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 489 | .. exception:: WindowsError |
| 490 | |
| 491 | Only available on Windows. |
| 492 | |
| 493 | |
| 494 | OS exceptions |
| 495 | ^^^^^^^^^^^^^ |
| 496 | |
| 497 | The following exceptions are subclasses of :exc:`OSError`, they get raised |
| 498 | depending on the system error code. |
| 499 | |
| 500 | .. exception:: BlockingIOError |
| 501 | |
| 502 | Raised when an operation would block on an object (e.g. socket) set |
| 503 | for non-blocking operation. |
| 504 | Corresponds to :c:data:`errno` ``EAGAIN``, ``EALREADY``, |
| 505 | ``EWOULDBLOCK`` and ``EINPROGRESS``. |
| 506 | |
Antoine Pitrou | f55011f | 2011-10-12 18:57:23 +0200 | [diff] [blame] | 507 | In addition to those of :exc:`OSError`, :exc:`BlockingIOError` can have |
| 508 | one more attribute: |
| 509 | |
| 510 | .. attribute:: characters_written |
| 511 | |
| 512 | An integer containing the number of characters written to the stream |
| 513 | before it blocked. This attribute is available when using the |
| 514 | buffered I/O classes from the :mod:`io` module. |
| 515 | |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 516 | .. exception:: ChildProcessError |
| 517 | |
| 518 | Raised when an operation on a child process failed. |
| 519 | Corresponds to :c:data:`errno` ``ECHILD``. |
| 520 | |
| 521 | .. exception:: ConnectionError |
| 522 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 523 | A base class for connection-related issues. |
| 524 | |
| 525 | Subclasses are :exc:`BrokenPipeError`, :exc:`ConnectionAbortedError`, |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 526 | :exc:`ConnectionRefusedError` and :exc:`ConnectionResetError`. |
| 527 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 528 | .. exception:: BrokenPipeError |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 529 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 530 | A subclass of :exc:`ConnectionError`, raised when trying to write on a |
| 531 | pipe while the other end has been closed, or trying to write on a socket |
| 532 | which has been shutdown for writing. |
| 533 | Corresponds to :c:data:`errno` ``EPIPE`` and ``ESHUTDOWN``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 534 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 535 | .. exception:: ConnectionAbortedError |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 536 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 537 | A subclass of :exc:`ConnectionError`, raised when a connection attempt |
| 538 | is aborted by the peer. |
| 539 | Corresponds to :c:data:`errno` ``ECONNABORTED``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 540 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 541 | .. exception:: ConnectionRefusedError |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 542 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 543 | A subclass of :exc:`ConnectionError`, raised when a connection attempt |
| 544 | is refused by the peer. |
| 545 | Corresponds to :c:data:`errno` ``ECONNREFUSED``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 546 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 547 | .. exception:: ConnectionResetError |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 548 | |
Ezio Melotti | b24d3cf | 2012-10-21 03:22:05 +0300 | [diff] [blame] | 549 | A subclass of :exc:`ConnectionError`, raised when a connection is |
| 550 | reset by the peer. |
| 551 | Corresponds to :c:data:`errno` ``ECONNRESET``. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 552 | |
| 553 | .. exception:: FileExistsError |
| 554 | |
| 555 | Raised when trying to create a file or directory which already exists. |
| 556 | Corresponds to :c:data:`errno` ``EEXIST``. |
| 557 | |
| 558 | .. exception:: FileNotFoundError |
| 559 | |
| 560 | Raised when a file or directory is requested but doesn't exist. |
| 561 | Corresponds to :c:data:`errno` ``ENOENT``. |
| 562 | |
| 563 | .. exception:: InterruptedError |
| 564 | |
| 565 | Raised when a system call is interrupted by an incoming signal. |
Victor Stinner | f70e1ca | 2015-03-30 21:16:11 +0200 | [diff] [blame] | 566 | Corresponds to :c:data:`errno` :py:data:`~errno.EINTR`. |
| 567 | |
| 568 | .. versionchanged:: 3.5 |
| 569 | Python now retries system calls when a syscall is interrupted by a |
| 570 | signal, except if the signal handler raises an exception (see :pep:`475` |
| 571 | for the rationale), instead of raising :exc:`InterruptedError`. |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 572 | |
| 573 | .. exception:: IsADirectoryError |
| 574 | |
| 575 | Raised when a file operation (such as :func:`os.remove`) is requested |
| 576 | on a directory. |
| 577 | Corresponds to :c:data:`errno` ``EISDIR``. |
| 578 | |
| 579 | .. exception:: NotADirectoryError |
| 580 | |
| 581 | Raised when a directory operation (such as :func:`os.listdir`) is requested |
| 582 | on something which is not a directory. |
| 583 | Corresponds to :c:data:`errno` ``ENOTDIR``. |
| 584 | |
| 585 | .. exception:: PermissionError |
| 586 | |
| 587 | Raised when trying to run an operation without the adequate access |
| 588 | rights - for example filesystem permissions. |
| 589 | Corresponds to :c:data:`errno` ``EACCES`` and ``EPERM``. |
| 590 | |
| 591 | .. exception:: ProcessLookupError |
| 592 | |
| 593 | Raised when a given process doesn't exist. |
| 594 | Corresponds to :c:data:`errno` ``ESRCH``. |
| 595 | |
| 596 | .. exception:: TimeoutError |
| 597 | |
| 598 | Raised when a system function timed out at the system level. |
| 599 | Corresponds to :c:data:`errno` ``ETIMEDOUT``. |
| 600 | |
| 601 | .. versionadded:: 3.3 |
| 602 | All the above :exc:`OSError` subclasses were added. |
| 603 | |
| 604 | |
| 605 | .. seealso:: |
| 606 | |
| 607 | :pep:`3151` - Reworking the OS and IO exception hierarchy |
Antoine Pitrou | f9c7746 | 2011-10-12 16:02:00 +0200 | [diff] [blame] | 608 | |
| 609 | |
| 610 | Warnings |
| 611 | -------- |
| 612 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 613 | The following exceptions are used as warning categories; see the :mod:`warnings` |
| 614 | module for more information. |
| 615 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 616 | .. exception:: Warning |
| 617 | |
| 618 | Base class for warning categories. |
| 619 | |
| 620 | |
| 621 | .. exception:: UserWarning |
| 622 | |
| 623 | Base class for warnings generated by user code. |
| 624 | |
| 625 | |
| 626 | .. exception:: DeprecationWarning |
| 627 | |
| 628 | Base class for warnings about deprecated features. |
| 629 | |
| 630 | |
| 631 | .. exception:: PendingDeprecationWarning |
| 632 | |
| 633 | Base class for warnings about features which will be deprecated in the future. |
| 634 | |
| 635 | |
| 636 | .. exception:: SyntaxWarning |
| 637 | |
| 638 | Base class for warnings about dubious syntax |
| 639 | |
| 640 | |
| 641 | .. exception:: RuntimeWarning |
| 642 | |
| 643 | Base class for warnings about dubious runtime behavior. |
| 644 | |
| 645 | |
| 646 | .. exception:: FutureWarning |
| 647 | |
| 648 | Base class for warnings about constructs that will change semantically in the |
| 649 | future. |
| 650 | |
| 651 | |
| 652 | .. exception:: ImportWarning |
| 653 | |
| 654 | Base class for warnings about probable mistakes in module imports. |
| 655 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 656 | |
| 657 | .. exception:: UnicodeWarning |
| 658 | |
| 659 | Base class for warnings related to Unicode. |
| 660 | |
Georg Brandl | 08be72d | 2010-10-24 15:11:22 +0000 | [diff] [blame] | 661 | |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 662 | .. exception:: BytesWarning |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 663 | |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 664 | Base class for warnings related to :class:`bytes` and :class:`bytearray`. |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 665 | |
Georg Brandl | 08be72d | 2010-10-24 15:11:22 +0000 | [diff] [blame] | 666 | |
| 667 | .. exception:: ResourceWarning |
| 668 | |
| 669 | Base class for warnings related to resource usage. |
| 670 | |
| 671 | .. versionadded:: 3.2 |
| 672 | |
| 673 | |
| 674 | |
Alexandre Vassalotti | c22c6f2 | 2009-07-21 00:51:58 +0000 | [diff] [blame] | 675 | Exception hierarchy |
| 676 | ------------------- |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 677 | |
| 678 | The class hierarchy for built-in exceptions is: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 679 | |
| 680 | .. literalinclude:: ../../Lib/test/exception_hierarchy.txt |