| .. _bltin-exceptions: |
| |
| Built-in Exceptions |
| =================== |
| |
| .. index:: |
| statement: try |
| statement: except |
| |
| In Python, all exceptions must be instances of a class that derives from |
| :class:`BaseException`. In a :keyword:`try` statement with an :keyword:`except` |
| clause that mentions a particular class, that clause also handles any exception |
| classes derived from that class (but not exception classes from which *it* is |
| derived). Two exception classes that are not related via subclassing are never |
| equivalent, even if they have the same name. |
| |
| .. index:: statement: raise |
| |
| The built-in exceptions listed below can be generated by the interpreter or |
| built-in functions. Except where mentioned, they have an "associated value" |
| indicating the detailed cause of the error. This may be a string or a tuple of |
| several items of information (e.g., an error code and a string explaining the |
| code). The associated value is usually passed as arguments to the exception |
| class's constructor. |
| |
| User code can raise built-in exceptions. This can be used to test an exception |
| handler or to report an error condition "just like" the situation in which the |
| interpreter raises the same exception; but beware that there is nothing to |
| prevent user code from raising an inappropriate error. |
| |
| The built-in exception classes can be sub-classed to define new exceptions; |
| programmers are encouraged to at least derive new exceptions from the |
| :exc:`Exception` class and not :exc:`BaseException`. More information on |
| defining exceptions is available in the Python Tutorial under |
| :ref:`tut-userexceptions`. |
| |
| The following exceptions are used mostly as base classes for other exceptions. |
| |
| .. exception:: BaseException |
| |
| The base class for all built-in exceptions. It is not meant to be directly |
| inherited by user-defined classes (for that, use :exc:`Exception`). If |
| :func:`bytes` or :func:`str` is called on an instance of this class, the |
| representation of the argument(s) to the instance are returned, or the empty |
| string when there were no arguments. |
| |
| .. attribute:: args |
| |
| The tuple of arguments given to the exception constructor. Some built-in |
| exceptions (like :exc:`IOError`) expect a certain number of arguments and |
| assign a special meaning to the elements of this tuple, while others are |
| usually called only with a single string giving an error message. |
| |
| .. method:: with_traceback(tb) |
| |
| This method sets *tb* as the new traceback for the exception and returns |
| the exception object. It is usually used in exception handling code like |
| this:: |
| |
| try: |
| ... |
| except SomeException: |
| tb = sys.exc_info()[2] |
| raise OtherException(...).with_traceback(tb) |
| |
| |
| .. exception:: Exception |
| |
| All built-in, non-system-exiting exceptions are derived from this class. All |
| user-defined exceptions should also be derived from this class. |
| |
| |
| .. exception:: ArithmeticError |
| |
| The base class for those built-in exceptions that are raised for various |
| arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`, |
| :exc:`FloatingPointError`. |
| |
| |
| .. exception:: BufferError |
| |
| Raised when a :ref:`buffer <bufferobjects>` related operation cannot be |
| performed. |
| |
| |
| .. exception:: LookupError |
| |
| The base class for the exceptions that are raised when a key or index used on |
| a mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`. This |
| can be raised directly by :func:`codecs.lookup`. |
| |
| |
| .. exception:: EnvironmentError |
| |
| The base class for exceptions that can occur outside the Python system: |
| :exc:`IOError`, :exc:`OSError`. When exceptions of this type are created with a |
| 2-tuple, the first item is available on the instance's :attr:`errno` attribute |
| (it is assumed to be an error number), and the second item is available on the |
| :attr:`strerror` attribute (it is usually the associated error message). The |
| tuple itself is also available on the :attr:`args` attribute. |
| |
| When an :exc:`EnvironmentError` exception is instantiated with a 3-tuple, the |
| first two items are available as above, while the third item is available on the |
| :attr:`filename` attribute. However, for backwards compatibility, the |
| :attr:`args` attribute contains only a 2-tuple of the first two constructor |
| arguments. |
| |
| The :attr:`filename` attribute is ``None`` when this exception is created with |
| other than 3 arguments. The :attr:`errno` and :attr:`strerror` attributes are |
| also ``None`` when the instance was created with other than 2 or 3 arguments. |
| In this last case, :attr:`args` contains the verbatim constructor arguments as a |
| tuple. |
| |
| |
| The following exceptions are the exceptions that are usually raised. |
| |
| .. exception:: AssertionError |
| |
| .. index:: statement: assert |
| |
| Raised when an :keyword:`assert` statement fails. |
| |
| |
| .. exception:: AttributeError |
| |
| Raised when an attribute reference (see :ref:`attribute-references`) or |
| assignment fails. (When an object does not support attribute references or |
| attribute assignments at all, :exc:`TypeError` is raised.) |
| |
| |
| .. exception:: EOFError |
| |
| Raised when one of the built-in functions (:func:`input` or :func:`raw_input`) |
| hits an end-of-file condition (EOF) without reading any data. (N.B.: the |
| :meth:`file.read` and :meth:`file.readline` methods return an empty string |
| when they hit EOF.) |
| |
| |
| .. exception:: FloatingPointError |
| |
| Raised when a floating point operation fails. This exception is always defined, |
| but can only be raised when Python is configured with the |
| ``--with-fpectl`` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is |
| defined in the :file:`pyconfig.h` file. |
| |
| |
| .. exception:: GeneratorExit |
| |
| Raise when a :term:`generator`\'s :meth:`close` method is called. It |
| directly inherits from :exc:`BaseException` instead of :exc:`Exception` since |
| it is technically not an error. |
| |
| |
| .. exception:: IOError |
| |
| Raised when an I/O operation (such as the built-in :func:`print` or |
| :func:`open` functions or a method of a :term:`file object`) fails for an |
| I/O-related reason, e.g., "file not found" or "disk full". |
| |
| This class is derived from :exc:`EnvironmentError`. See the discussion above |
| for more information on exception instance attributes. |
| |
| |
| .. exception:: ImportError |
| |
| Raised when an :keyword:`import` statement fails to find the module definition |
| or when a ``from ... import`` fails to find a name that is to be imported. |
| |
| |
| .. exception:: IndexError |
| |
| Raised when a sequence subscript is out of range. (Slice indices are |
| silently truncated to fall in the allowed range; if an index is not an |
| integer, :exc:`TypeError` is raised.) |
| |
| .. XXX xref to sequences |
| |
| |
| .. exception:: KeyError |
| |
| Raised when a mapping (dictionary) key is not found in the set of existing keys. |
| |
| .. XXX xref to mapping objects? |
| |
| |
| .. exception:: KeyboardInterrupt |
| |
| Raised when the user hits the interrupt key (normally :kbd:`Control-C` or |
| :kbd:`Delete`). During execution, a check for interrupts is made |
| regularly. The exception inherits from :exc:`BaseException` so as to not be |
| accidentally caught by code that catches :exc:`Exception` and thus prevent |
| the interpreter from exiting. |
| |
| |
| .. exception:: MemoryError |
| |
| Raised when an operation runs out of memory but the situation may still be |
| rescued (by deleting some objects). The associated value is a string indicating |
| what kind of (internal) operation ran out of memory. Note that because of the |
| underlying memory management architecture (C's :c:func:`malloc` function), the |
| interpreter may not always be able to completely recover from this situation; it |
| nevertheless raises an exception so that a stack traceback can be printed, in |
| case a run-away program was the cause. |
| |
| |
| .. exception:: NameError |
| |
| Raised when a local or global name is not found. This applies only to |
| unqualified names. The associated value is an error message that includes the |
| name that could not be found. |
| |
| |
| .. exception:: NotImplementedError |
| |
| This exception is derived from :exc:`RuntimeError`. In user defined base |
| classes, abstract methods should raise this exception when they require derived |
| classes to override the method. |
| |
| |
| .. exception:: OSError |
| |
| .. index:: module: errno |
| |
| This exception is derived from :exc:`EnvironmentError`. It is raised when a |
| function returns a system-related error (not for illegal argument types or |
| other incidental errors). The :attr:`errno` attribute is a numeric error |
| code from :c:data:`errno`, and the :attr:`strerror` attribute is the |
| corresponding string, as would be printed by the C function :c:func:`perror`. |
| See the module :mod:`errno`, which contains names for the error codes defined |
| by the underlying operating system. |
| |
| For exceptions that involve a file system path (such as :func:`chdir` or |
| :func:`unlink`), the exception instance will contain a third attribute, |
| :attr:`filename`, which is the file name passed to the function. |
| |
| |
| .. exception:: OverflowError |
| |
| Raised when the result of an arithmetic operation is too large to be |
| represented. This cannot occur for integers (which would rather raise |
| :exc:`MemoryError` than give up). Because of the lack of standardization of |
| floating point exception handling in C, most floating point operations also |
| aren't checked. |
| |
| |
| .. exception:: ReferenceError |
| |
| This exception is raised when a weak reference proxy, created by the |
| :func:`weakref.proxy` function, is used to access an attribute of the referent |
| after it has been garbage collected. For more information on weak references, |
| see the :mod:`weakref` module. |
| |
| |
| .. exception:: RuntimeError |
| |
| Raised when an error is detected that doesn't fall in any of the other |
| categories. The associated value is a string indicating what precisely went |
| wrong. (This exception is mostly a relic from a previous version of the |
| interpreter; it is not used very much any more.) |
| |
| |
| .. exception:: StopIteration |
| |
| Raised by built-in function :func:`next` and an :term:`iterator`\'s |
| :meth:`__next__` method to signal that there are no further values. |
| |
| |
| .. exception:: SyntaxError |
| |
| Raised when the parser encounters a syntax error. This may occur in an |
| :keyword:`import` statement, in a call to the built-in functions :func:`exec` |
| or :func:`eval`, or when reading the initial script or standard input |
| (also interactively). |
| |
| Instances of this class have attributes :attr:`filename`, :attr:`lineno`, |
| :attr:`offset` and :attr:`text` for easier access to the details. :func:`str` |
| of the exception instance returns only the message. |
| |
| |
| .. exception:: IndentationError |
| |
| Base class for syntax errors related to incorrect indentation. This is a |
| subclass of :exc:`SyntaxError`. |
| |
| |
| .. exception:: TabError |
| |
| Raised when indentation contains an inconsistent use of tabs and spaces. |
| This is a subclass of :exc:`IndentationError`. |
| |
| |
| .. exception:: SystemError |
| |
| Raised when the interpreter finds an internal error, but the situation does not |
| look so serious to cause it to abandon all hope. The associated value is a |
| string indicating what went wrong (in low-level terms). |
| |
| You should report this to the author or maintainer of your Python interpreter. |
| Be sure to report the version of the Python interpreter (``sys.version``; it is |
| also printed at the start of an interactive Python session), the exact error |
| message (the exception's associated value) and if possible the source of the |
| program that triggered the error. |
| |
| |
| .. exception:: SystemExit |
| |
| This exception is raised by the :func:`sys.exit` function. When it is not |
| handled, the Python interpreter exits; no stack traceback is printed. If the |
| associated value is an integer, it specifies the system exit status (passed |
| to C's :c:func:`exit` function); if it is ``None``, the exit status is zero; |
| if it has another type (such as a string), the object's value is printed and |
| the exit status is one. |
| |
| Instances have an attribute :attr:`code` which is set to the proposed exit |
| status or error message (defaulting to ``None``). Also, this exception derives |
| directly from :exc:`BaseException` and not :exc:`Exception`, since it is not |
| technically an error. |
| |
| A call to :func:`sys.exit` is translated into an exception so that clean-up |
| handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be |
| executed, and so that a debugger can execute a script without running the risk |
| of losing control. The :func:`os._exit` function can be used if it is |
| absolutely positively necessary to exit immediately (for example, in the child |
| process after a call to :func:`fork`). |
| |
| The exception inherits from :exc:`BaseException` instead of :exc:`Exception` so |
| that it is not accidentally caught by code that catches :exc:`Exception`. This |
| allows the exception to properly propagate up and cause the interpreter to exit. |
| |
| |
| .. exception:: TypeError |
| |
| Raised when an operation or function is applied to an object of inappropriate |
| type. The associated value is a string giving details about the type mismatch. |
| |
| |
| .. exception:: UnboundLocalError |
| |
| Raised when a reference is made to a local variable in a function or method, but |
| no value has been bound to that variable. This is a subclass of |
| :exc:`NameError`. |
| |
| |
| .. exception:: UnicodeError |
| |
| Raised when a Unicode-related encoding or decoding error occurs. It is a |
| subclass of :exc:`ValueError`. |
| |
| |
| .. exception:: UnicodeEncodeError |
| |
| Raised when a Unicode-related error occurs during encoding. It is a subclass of |
| :exc:`UnicodeError`. |
| |
| |
| .. exception:: UnicodeDecodeError |
| |
| Raised when a Unicode-related error occurs during decoding. It is a subclass of |
| :exc:`UnicodeError`. |
| |
| |
| .. exception:: UnicodeTranslateError |
| |
| Raised when a Unicode-related error occurs during translating. It is a subclass |
| of :exc:`UnicodeError`. |
| |
| |
| .. exception:: ValueError |
| |
| Raised when a built-in operation or function receives an argument that has the |
| right type but an inappropriate value, and the situation is not described by a |
| more precise exception such as :exc:`IndexError`. |
| |
| |
| .. exception:: VMSError |
| |
| Only available on VMS. Raised when a VMS-specific error occurs. |
| |
| |
| .. exception:: WindowsError |
| |
| Raised when a Windows-specific error occurs or when the error number does not |
| correspond to an :c:data:`errno` value. The :attr:`winerror` and |
| :attr:`strerror` values are created from the return values of the |
| :c:func:`GetLastError` and :c:func:`FormatMessage` functions from the Windows |
| Platform API. The :attr:`errno` value maps the :attr:`winerror` value to |
| corresponding ``errno.h`` values. This is a subclass of :exc:`OSError`. |
| |
| |
| .. exception:: ZeroDivisionError |
| |
| Raised when the second argument of a division or modulo operation is zero. The |
| associated value is a string indicating the type of the operands and the |
| operation. |
| |
| |
| The following exceptions are used as warning categories; see the :mod:`warnings` |
| module for more information. |
| |
| .. exception:: Warning |
| |
| Base class for warning categories. |
| |
| |
| .. exception:: UserWarning |
| |
| Base class for warnings generated by user code. |
| |
| |
| .. exception:: DeprecationWarning |
| |
| Base class for warnings about deprecated features. |
| |
| |
| .. exception:: PendingDeprecationWarning |
| |
| Base class for warnings about features which will be deprecated in the future. |
| |
| |
| .. exception:: SyntaxWarning |
| |
| Base class for warnings about dubious syntax |
| |
| |
| .. exception:: RuntimeWarning |
| |
| Base class for warnings about dubious runtime behavior. |
| |
| |
| .. exception:: FutureWarning |
| |
| Base class for warnings about constructs that will change semantically in the |
| future. |
| |
| |
| .. exception:: ImportWarning |
| |
| Base class for warnings about probable mistakes in module imports. |
| |
| |
| .. exception:: UnicodeWarning |
| |
| Base class for warnings related to Unicode. |
| |
| |
| .. exception:: BytesWarning |
| |
| Base class for warnings related to :class:`bytes` and :class:`buffer`. |
| |
| |
| .. exception:: ResourceWarning |
| |
| Base class for warnings related to resource usage. |
| |
| .. versionadded:: 3.2 |
| |
| |
| |
| Exception hierarchy |
| ------------------- |
| |
| The class hierarchy for built-in exceptions is: |
| |
| .. literalinclude:: ../../Lib/test/exception_hierarchy.txt |