1 .. _bltin-exceptions: 2 3 Built-in Exceptions 4 =================== 5 6 .. module:: exceptions 7 :synopsis: Standard exception classes. 8 9 10 Exceptions should be class objects. The exceptions are defined in the module 11 :mod:`exceptions`. This module never needs to be imported explicitly: the 12 exceptions are provided in the built-in namespace as well as the 13 :mod:`exceptions` module. 14 15 .. index:: 16 statement: try 17 statement: except 18 19 For class exceptions, in a :keyword:`try` statement with an :keyword:`except` 20 clause that mentions a particular class, that clause also handles any exception 21 classes derived from that class (but not exception classes from which *it* is 22 derived). Two exception classes that are not related via subclassing are never 23 equivalent, even if they have the same name. 24 25 .. index:: statement: raise 26 27 The built-in exceptions listed below can be generated by the interpreter or 28 built-in functions. Except where mentioned, they have an "associated value" 29 indicating the detailed cause of the error. This may be a string or a tuple 30 containing several items of information (e.g., an error code and a string 31 explaining the code). The associated value is the second argument to the 32 :keyword:`raise` statement. If the exception class is derived from the standard 33 root class :exc:`BaseException`, the associated value is present as the 34 exception instance's :attr:`args` attribute. 35 36 User code can raise built-in exceptions. This can be used to test an exception 37 handler or to report an error condition "just like" the situation in which the 38 interpreter raises the same exception; but beware that there is nothing to 39 prevent user code from raising an inappropriate error. 40 41 The built-in exception classes can be subclassed to define new exceptions; 42 programmers are encouraged to derive new exceptions from the :exc:`Exception` 43 class or one of its subclasses, and not from :exc:`BaseException`. More 44 information on defining exceptions is available in the Python Tutorial under 45 :ref:`tut-userexceptions`. 46 47 The following exceptions are only used as base classes for other exceptions. 48 49 .. exception:: BaseException 50 51 The base class for all built-in exceptions. It is not meant to be directly 52 inherited by user-defined classes (for that, use :exc:`Exception`). If 53 :func:`str` or :func:`unicode` is called on an instance of this class, the 54 representation of the argument(s) to the instance are returned, or the empty 55 string when there were no arguments. 56 57 .. versionadded:: 2.5 58 59 .. attribute:: args 60 61 The tuple of arguments given to the exception constructor. Some built-in 62 exceptions (like :exc:`IOError`) expect a certain number of arguments and 63 assign a special meaning to the elements of this tuple, while others are 64 usually called only with a single string giving an error message. 65 66 67 .. exception:: Exception 68 69 All built-in, non-system-exiting exceptions are derived from this class. All 70 user-defined exceptions should also be derived from this class. 71 72 .. versionchanged:: 2.5 73 Changed to inherit from :exc:`BaseException`. 74 75 76 .. exception:: StandardError 77 78 The base class for all built-in exceptions except :exc:`StopIteration`, 79 :exc:`GeneratorExit`, :exc:`KeyboardInterrupt` and :exc:`SystemExit`. 80 :exc:`StandardError` itself is derived from :exc:`Exception`. 81 82 83 .. exception:: ArithmeticError 84 85 The base class for those built-in exceptions that are raised for various 86 arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`, 87 :exc:`FloatingPointError`. 88 89 90 .. exception:: BufferError 91 92 Raised when a :ref:`buffer <bufferobjects>` related operation cannot be 93 performed. 94 95 96 .. exception:: LookupError 97 98 The base class for the exceptions that are raised when a key or index used on 99 a mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`. This 100 can be raised directly by :func:`codecs.lookup`. 101 102 103 .. exception:: EnvironmentError 104 105 The base class for exceptions that can occur outside the Python system: 106 :exc:`IOError`, :exc:`OSError`. When exceptions of this type are created with a 107 2-tuple, the first item is available on the instance's :attr:`errno` attribute 108 (it is assumed to be an error number), and the second item is available on the 109 :attr:`strerror` attribute (it is usually the associated error message). The 110 tuple itself is also available on the :attr:`args` attribute. 111 112 .. versionadded:: 1.5.2 113 114 When an :exc:`EnvironmentError` exception is instantiated with a 3-tuple, the 115 first two items are available as above, while the third item is available on the 116 :attr:`filename` attribute. However, for backwards compatibility, the 117 :attr:`args` attribute contains only a 2-tuple of the first two constructor 118 arguments. 119 120 The :attr:`filename` attribute is ``None`` when this exception is created with 121 other than 3 arguments. The :attr:`errno` and :attr:`strerror` attributes are 122 also ``None`` when the instance was created with other than 2 or 3 arguments. 123 In this last case, :attr:`args` contains the verbatim constructor arguments as a 124 tuple. 125 126 The following exceptions are the exceptions that are actually raised. 127 128 129 .. exception:: AssertionError 130 131 .. index:: statement: assert 132 133 Raised when an :keyword:`assert` statement fails. 134 135 136 .. exception:: AttributeError 137 138 Raised when an attribute reference (see :ref:`attribute-references`) or 139 assignment fails. (When an object does not support attribute references or 140 attribute assignments at all, :exc:`TypeError` is raised.) 141 142 143 .. exception:: EOFError 144 145 Raised when one of the built-in functions (:func:`input` or :func:`raw_input`) 146 hits an end-of-file condition (EOF) without reading any data. (N.B.: the 147 :meth:`file.read` and :meth:`file.readline` methods return an empty string 148 when they hit EOF.) 149 150 151 .. exception:: FloatingPointError 152 153 Raised when a floating point operation fails. This exception is always defined, 154 but can only be raised when Python is configured with the 155 ``--with-fpectl`` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is 156 defined in the :file:`pyconfig.h` file. 157 158 159 .. exception:: GeneratorExit 160 161 Raised when a :term:`generator`\'s :meth:`close` method is called. It 162 directly inherits from :exc:`BaseException` instead of :exc:`StandardError` 163 since it is technically not an error. 164 165 .. versionadded:: 2.5 166 167 .. versionchanged:: 2.6 168 Changed to inherit from :exc:`BaseException`. 169 170 .. exception:: IOError 171 172 Raised when an I/O operation (such as a :keyword:`print` statement, the built-in 173 :func:`open` function or a method of a file object) fails for an I/O-related 174 reason, e.g., "file not found" or "disk full". 175 176 This class is derived from :exc:`EnvironmentError`. See the discussion above 177 for more information on exception instance attributes. 178 179 .. versionchanged:: 2.6 180 Changed :exc:`socket.error` to use this as a base class. 181 182 183 .. exception:: ImportError 184 185 Raised when an :keyword:`import` statement fails to find the module definition 186 or when a ``from ... import`` fails to find a name that is to be imported. 187 188 189 .. exception:: IndexError 190 191 Raised when a sequence subscript is out of range. (Slice indices are silently 192 truncated to fall in the allowed range; if an index is not a plain integer, 193 :exc:`TypeError` is raised.) 194 195 .. XXX xref to sequences 196 197 198 .. exception:: KeyError 199 200 Raised when a mapping (dictionary) key is not found in the set of existing keys. 201 202 .. XXX xref to mapping objects? 203 204 205 .. exception:: KeyboardInterrupt 206 207 Raised when the user hits the interrupt key (normally :kbd:`Control-C` or 208 :kbd:`Delete`). During execution, a check for interrupts is made regularly. 209 Interrupts typed when a built-in function :func:`input` or :func:`raw_input` is 210 waiting for input also raise this exception. The exception inherits from 211 :exc:`BaseException` so as to not be accidentally caught by code that catches 212 :exc:`Exception` and thus prevent the interpreter from exiting. 213 214 .. versionchanged:: 2.5 215 Changed to inherit from :exc:`BaseException`. 216 217 218 .. exception:: MemoryError 219 220 Raised when an operation runs out of memory but the situation may still be 221 rescued (by deleting some objects). The associated value is a string indicating 222 what kind of (internal) operation ran out of memory. Note that because of the 223 underlying memory management architecture (C's :c:func:`malloc` function), the 224 interpreter may not always be able to completely recover from this situation; it 225 nevertheless raises an exception so that a stack traceback can be printed, in 226 case a run-away program was the cause. 227 228 229 .. exception:: NameError 230 231 Raised when a local or global name is not found. This applies only to 232 unqualified names. The associated value is an error message that includes the 233 name that could not be found. 234 235 236 .. exception:: NotImplementedError 237 238 This exception is derived from :exc:`RuntimeError`. In user defined base 239 classes, abstract methods should raise this exception when they require derived 240 classes to override the method. 241 242 .. versionadded:: 1.5.2 243 244 245 .. exception:: OSError 246 247 .. index:: module: errno 248 249 This exception is derived from :exc:`EnvironmentError`. It is raised when a 250 function returns a system-related error (not for illegal argument types or 251 other incidental errors). The :attr:`errno` attribute is a numeric error 252 code from :c:data:`errno`, and the :attr:`strerror` attribute is the 253 corresponding string, as would be printed by the C function :c:func:`perror`. 254 See the module :mod:`errno`, which contains names for the error codes defined 255 by the underlying operating system. 256 257 For exceptions that involve a file system path (such as :func:`chdir` or 258 :func:`unlink`), the exception instance will contain a third attribute, 259 :attr:`filename`, which is the file name passed to the function. 260 261 .. versionadded:: 1.5.2 262 263 264 .. exception:: OverflowError 265 266 Raised when the result of an arithmetic operation is too large to be 267 represented. This cannot occur for long integers (which would rather raise 268 :exc:`MemoryError` than give up) and for most operations with plain integers, 269 which return a long integer instead. Because of the lack of standardization 270 of floating point exception handling in C, most floating point operations 271 also aren't checked. 272 273 274 .. exception:: ReferenceError 275 276 This exception is raised when a weak reference proxy, created by the 277 :func:`weakref.proxy` function, is used to access an attribute of the referent 278 after it has been garbage collected. For more information on weak references, 279 see the :mod:`weakref` module. 280 281 .. versionadded:: 2.2 282 Previously known as the :exc:`weakref.ReferenceError` exception. 283 284 285 .. exception:: RuntimeError 286 287 Raised when an error is detected that doesn't fall in any of the other 288 categories. The associated value is a string indicating what precisely went 289 wrong. 290 291 292 .. exception:: StopIteration 293 294 Raised by an :term:`iterator`\'s :meth:`~iterator.next` method to signal that 295 there are no further values. This is derived from :exc:`Exception` rather 296 than :exc:`StandardError`, since this is not considered an error in its 297 normal application. 298 299 .. versionadded:: 2.2 300 301 302 .. exception:: SyntaxError 303 304 Raised when the parser encounters a syntax error. This may occur in an 305 :keyword:`import` statement, in an :keyword:`exec` statement, in a call to the 306 built-in function :func:`eval` or :func:`input`, or when reading the initial 307 script or standard input (also interactively). 308 309 Instances of this class have attributes :attr:`filename`, :attr:`lineno`, 310 :attr:`offset` and :attr:`text` for easier access to the details. :func:`str` 311 of the exception instance returns only the message. 312 313 314 .. exception:: IndentationError 315 316 Base class for syntax errors related to incorrect indentation. This is a 317 subclass of :exc:`SyntaxError`. 318 319 320 .. exception:: TabError 321 322 Raised when indentation contains an inconsistent use of tabs and spaces. 323 This is a subclass of :exc:`IndentationError`. 324 325 326 .. exception:: SystemError 327 328 Raised when the interpreter finds an internal error, but the situation does not 329 look so serious to cause it to abandon all hope. The associated value is a 330 string indicating what went wrong (in low-level terms). 331 332 You should report this to the author or maintainer of your Python interpreter. 333 Be sure to report the version of the Python interpreter (``sys.version``; it is 334 also printed at the start of an interactive Python session), the exact error 335 message (the exception's associated value) and if possible the source of the 336 program that triggered the error. 337 338 339 .. exception:: SystemExit 340 341 This exception is raised by the :func:`sys.exit` function. When it is not 342 handled, the Python interpreter exits; no stack traceback is printed. If the 343 associated value is a plain integer, it specifies the system exit status (passed 344 to C's :c:func:`exit` function); if it is ``None``, the exit status is zero; if 345 it has another type (such as a string), the object's value is printed and the 346 exit status is one. 347 348 Instances have an attribute :attr:`!code` which is set to the proposed exit 349 status or error message (defaulting to ``None``). Also, this exception derives 350 directly from :exc:`BaseException` and not :exc:`StandardError`, since it is not 351 technically an error. 352 353 A call to :func:`sys.exit` is translated into an exception so that clean-up 354 handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be 355 executed, and so that a debugger can execute a script without running the risk 356 of losing control. The :func:`os._exit` function can be used if it is 357 absolutely positively necessary to exit immediately (for example, in the child 358 process after a call to :func:`os.fork`). 359 360 The exception inherits from :exc:`BaseException` instead of :exc:`StandardError` 361 or :exc:`Exception` so that it is not accidentally caught by code that catches 362 :exc:`Exception`. This allows the exception to properly propagate up and cause 363 the interpreter to exit. 364 365 .. versionchanged:: 2.5 366 Changed to inherit from :exc:`BaseException`. 367 368 369 .. exception:: TypeError 370 371 Raised when an operation or function is applied to an object of inappropriate 372 type. The associated value is a string giving details about the type mismatch. 373 374 375 .. exception:: UnboundLocalError 376 377 Raised when a reference is made to a local variable in a function or method, but 378 no value has been bound to that variable. This is a subclass of 379 :exc:`NameError`. 380 381 .. versionadded:: 2.0 382 383 384 .. exception:: UnicodeError 385 386 Raised when a Unicode-related encoding or decoding error occurs. It is a 387 subclass of :exc:`ValueError`. 388 389 :exc:`UnicodeError` has attributes that describe the encoding or decoding 390 error. For example, ``err.object[err.start:err.end]`` gives the particular 391 invalid input that the codec failed on. 392 393 .. attribute:: encoding 394 395 The name of the encoding that raised the error. 396 397 .. attribute:: reason 398 399 A string describing the specific codec error. 400 401 .. attribute:: object 402 403 The object the codec was attempting to encode or decode. 404 405 .. attribute:: start 406 407 The first index of invalid data in :attr:`object`. 408 409 .. attribute:: end 410 411 The index after the last invalid data in :attr:`object`. 412 413 .. versionadded:: 2.0 414 415 416 .. exception:: UnicodeEncodeError 417 418 Raised when a Unicode-related error occurs during encoding. It is a subclass of 419 :exc:`UnicodeError`. 420 421 .. versionadded:: 2.3 422 423 424 .. exception:: UnicodeDecodeError 425 426 Raised when a Unicode-related error occurs during decoding. It is a subclass of 427 :exc:`UnicodeError`. 428 429 .. versionadded:: 2.3 430 431 432 .. exception:: UnicodeTranslateError 433 434 Raised when a Unicode-related error occurs during translating. It is a subclass 435 of :exc:`UnicodeError`. 436 437 .. versionadded:: 2.3 438 439 440 .. exception:: ValueError 441 442 Raised when an operation or function receives an argument that has the 443 right type but an inappropriate value, and the situation is not described by a 444 more precise exception such as :exc:`IndexError`. 445 446 447 .. exception:: VMSError 448 449 Only available on VMS. Raised when a VMS-specific error occurs. 450 451 452 .. exception:: WindowsError 453 454 Raised when a Windows-specific error occurs or when the error number does not 455 correspond to an :c:data:`errno` value. The :attr:`winerror` and 456 :attr:`strerror` values are created from the return values of the 457 :c:func:`GetLastError` and :c:func:`FormatMessage` functions from the Windows 458 Platform API. The :attr:`errno` value maps the :attr:`winerror` value to 459 corresponding ``errno.h`` values. This is a subclass of :exc:`OSError`. 460 461 .. versionadded:: 2.0 462 463 .. versionchanged:: 2.5 464 Previous versions put the :c:func:`GetLastError` codes into :attr:`errno`. 465 466 467 .. exception:: ZeroDivisionError 468 469 Raised when the second argument of a division or modulo operation is zero. The 470 associated value is a string indicating the type of the operands and the 471 operation. 472 473 The following exceptions are used as warning categories; see the :mod:`warnings` 474 module for more information. 475 476 477 .. exception:: Warning 478 479 Base class for warning categories. 480 481 482 .. exception:: UserWarning 483 484 Base class for warnings generated by user code. 485 486 487 .. exception:: DeprecationWarning 488 489 Base class for warnings about deprecated features. 490 491 492 .. exception:: PendingDeprecationWarning 493 494 Base class for warnings about features which will be deprecated in the future. 495 496 497 .. exception:: SyntaxWarning 498 499 Base class for warnings about dubious syntax. 500 501 502 .. exception:: RuntimeWarning 503 504 Base class for warnings about dubious runtime behavior. 505 506 507 .. exception:: FutureWarning 508 509 Base class for warnings about constructs that will change semantically in the 510 future. 511 512 513 .. exception:: ImportWarning 514 515 Base class for warnings about probable mistakes in module imports. 516 517 .. versionadded:: 2.5 518 519 520 .. exception:: UnicodeWarning 521 522 Base class for warnings related to Unicode. 523 524 .. versionadded:: 2.5 525 526 527 Exception hierarchy 528 ------------------- 529 530 The class hierarchy for built-in exceptions is: 531 532 .. literalinclude:: ../../Lib/test/exception_hierarchy.txt 533
