| .. _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 subclassed to define new exceptions; |
| programmers are encouraged to derive new exceptions from the :exc:`Exception` |
| class or one of its subclasses, and not from :exc:`BaseException`. More |
| information on defining exceptions is available in the Python Tutorial under |
| :ref:`tut-userexceptions`. |
| |
| When raising (or re-raising) an exception in an :keyword:`except` or |
| :keyword:`finally` clause |
| :attr:`__context__` is automatically set to the last exception caught; if the |
| new exception is not handled the traceback that is eventually displayed will |
| include the originating exception(s) and the final exception. |
| |
| When raising a new exception (rather than using a bare ``raise`` to re-raise |
| the exception currently being handled), the implicit exception context can be |
| supplemented with an explicit cause by using :keyword:`from` with |
| :keyword:`raise`:: |
| |
| raise new_exc from original_exc |
| |
| The expression following :keyword:`from` must be an exception or ``None``. It |
| will be set as :attr:`__cause__` on the raised exception. Setting |
| :attr:`__cause__` also implicitly sets the :attr:`__suppress_context__` |
| attribute to ``True``, so that using ``raise new_exc from None`` |
| effectively replaces the old exception with the new one for display |
| purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`, while |
| leaving the old exception available in :attr:`__context__` for introspection |
| when debugging. |
| |
| The default traceback display code shows these chained exceptions in |
| addition to the traceback for the exception itself. An explicitly chained |
| exception in :attr:`__cause__` is always shown when present. An implicitly |
| chained exception in :attr:`__context__` is shown only if :attr:`__cause__` |
| is :const:`None` and :attr:`__suppress_context__` is false. |
| |
| In either case, the exception itself is always shown after any chained |
| exceptions so that the final line of the traceback always shows the last |
| exception that was raised. |
| |
| |
| Base classes |
| ------------ |
| |
| 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:`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:`OSError`) 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`. |
| |
| |
| Concrete exceptions |
| ------------------- |
| |
| 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 the :func:`input` function hits an end-of-file condition (EOF) |
| without reading any data. (N.B.: the :meth:`io.IOBase.read` and |
| :meth:`io.IOBase.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 |
| |
| Raised 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:: 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. |
| |
| The :attr:`name` and :attr:`path` attributes can be set using keyword-only |
| arguments to the constructor. When set they represent the name of the module |
| that was attempted to be imported and the path to any file which triggered |
| the exception, respectively. |
| |
| .. versionchanged:: 3.3 |
| Added the :attr:`name` and :attr:`path` attributes. |
| |
| |
| .. 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 raised when a system function returns a system-related |
| error, including I/O failures such as "file not found" or "disk full" |
| (not for illegal argument types or other incidental errors). Often a |
| subclass of :exc:`OSError` will actually be raised as described in |
| `OS exceptions`_ below. The :attr:`errno` attribute is a numeric error |
| code from the C variable :c:data:`errno`. |
| |
| Under Windows, the :attr:`winerror` attribute gives you the native |
| Windows error code. The :attr:`errno` attribute is then an approximate |
| translation, in POSIX terms, of that native error code. |
| |
| Under all platforms, the :attr:`strerror` attribute is the corresponding |
| error message as provided by the operating system (as formatted by the C |
| functions :c:func:`perror` under POSIX, and :c:func:`FormatMessage` |
| Windows). |
| |
| For exceptions that involve a file system path (such as :func:`open` or |
| :func:`os.unlink`), the exception instance will contain an additional |
| attribute, :attr:`filename`, which is the file name passed to the function. |
| For functions that involve two file system paths (such as |
| :func:`os.rename`), the exception instance will contain a second |
| :attr:`filename2` attribute corresponding to the second file name passed |
| to the function. |
| |
| |
| .. versionchanged:: 3.3 |
| :exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`, |
| :exc:`VMSError`, :exc:`socket.error`, :exc:`select.error` and |
| :exc:`mmap.error` have been merged into :exc:`OSError`. |
| |
| .. versionchanged:: 3.4 |
| The :attr:`filename` attribute is now the original file name passed to |
| the function, instead of the name encoded to or decoded from the |
| filesystem encoding. Also, the :attr:`filename2` attribute was added. |
| |
| |
| .. 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). However, for historical reasons, |
| OverflowError is sometimes raised for integers that are outside a required |
| range. Because of the lack of standardization of floating point exception |
| handling in C, most floating point operations are not 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. |
| |
| |
| .. exception:: StopIteration |
| |
| Raised by built-in function :func:`next` and an :term:`iterator`\'s |
| :meth:`~iterator.__next__` method to signal that there are no further |
| items produced by the iterator. |
| |
| The exception object has a single attribute :attr:`value`, which is |
| given as an argument when constructing the exception, and defaults |
| to :const:`None`. |
| |
| When a generator function returns, a new :exc:`StopIteration` instance is |
| raised, and the value returned by the function is used as the |
| :attr:`value` parameter to the constructor of the exception. |
| |
| .. versionchanged:: 3.3 |
| Added ``value`` attribute and the ability for generator functions to |
| use it to return a value. |
| |
| .. 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. It 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. When it is not |
| handled, the Python interpreter exits; no stack traceback is printed. The |
| constructor accepts the same optional argument passed to :func:`sys.exit`. |
| If the 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. |
| |
| 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:`os.fork`). |
| |
| .. attribute:: code |
| |
| The exit status or error message that is passed to the constructor. |
| (Defaults to ``None``.) |
| |
| |
| .. 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`. |
| |
| :exc:`UnicodeError` has attributes that describe the encoding or decoding |
| error. For example, ``err.object[err.start:err.end]`` gives the particular |
| invalid input that the codec failed on. |
| |
| .. attribute:: encoding |
| |
| The name of the encoding that raised the error. |
| |
| .. attribute:: reason |
| |
| A string describing the specific codec error. |
| |
| .. attribute:: object |
| |
| The object the codec was attempting to encode or decode. |
| |
| .. attribute:: start |
| |
| The first index of invalid data in :attr:`object`. |
| |
| .. attribute:: end |
| |
| The index after the last invalid data in :attr:`object`. |
| |
| |
| .. 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:: 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 kept for compatibility with previous versions; |
| starting from Python 3.3, they are aliases of :exc:`OSError`. |
| |
| .. exception:: EnvironmentError |
| |
| .. exception:: IOError |
| |
| .. exception:: WindowsError |
| |
| Only available on Windows. |
| |
| |
| OS exceptions |
| ^^^^^^^^^^^^^ |
| |
| The following exceptions are subclasses of :exc:`OSError`, they get raised |
| depending on the system error code. |
| |
| .. exception:: BlockingIOError |
| |
| Raised when an operation would block on an object (e.g. socket) set |
| for non-blocking operation. |
| Corresponds to :c:data:`errno` ``EAGAIN``, ``EALREADY``, |
| ``EWOULDBLOCK`` and ``EINPROGRESS``. |
| |
| In addition to those of :exc:`OSError`, :exc:`BlockingIOError` can have |
| one more attribute: |
| |
| .. attribute:: characters_written |
| |
| An integer containing the number of characters written to the stream |
| before it blocked. This attribute is available when using the |
| buffered I/O classes from the :mod:`io` module. |
| |
| .. exception:: ChildProcessError |
| |
| Raised when an operation on a child process failed. |
| Corresponds to :c:data:`errno` ``ECHILD``. |
| |
| .. exception:: ConnectionError |
| |
| A base class for connection-related issues. |
| |
| Subclasses are :exc:`BrokenPipeError`, :exc:`ConnectionAbortedError`, |
| :exc:`ConnectionRefusedError` and :exc:`ConnectionResetError`. |
| |
| .. exception:: BrokenPipeError |
| |
| A subclass of :exc:`ConnectionError`, raised when trying to write on a |
| pipe while the other end has been closed, or trying to write on a socket |
| which has been shutdown for writing. |
| Corresponds to :c:data:`errno` ``EPIPE`` and ``ESHUTDOWN``. |
| |
| .. exception:: ConnectionAbortedError |
| |
| A subclass of :exc:`ConnectionError`, raised when a connection attempt |
| is aborted by the peer. |
| Corresponds to :c:data:`errno` ``ECONNABORTED``. |
| |
| .. exception:: ConnectionRefusedError |
| |
| A subclass of :exc:`ConnectionError`, raised when a connection attempt |
| is refused by the peer. |
| Corresponds to :c:data:`errno` ``ECONNREFUSED``. |
| |
| .. exception:: ConnectionResetError |
| |
| A subclass of :exc:`ConnectionError`, raised when a connection is |
| reset by the peer. |
| Corresponds to :c:data:`errno` ``ECONNRESET``. |
| |
| .. exception:: FileExistsError |
| |
| Raised when trying to create a file or directory which already exists. |
| Corresponds to :c:data:`errno` ``EEXIST``. |
| |
| .. exception:: FileNotFoundError |
| |
| Raised when a file or directory is requested but doesn't exist. |
| Corresponds to :c:data:`errno` ``ENOENT``. |
| |
| .. exception:: InterruptedError |
| |
| Raised when a system call is interrupted by an incoming signal. |
| Corresponds to :c:data:`errno` ``EINTR``. |
| |
| .. exception:: IsADirectoryError |
| |
| Raised when a file operation (such as :func:`os.remove`) is requested |
| on a directory. |
| Corresponds to :c:data:`errno` ``EISDIR``. |
| |
| .. exception:: NotADirectoryError |
| |
| Raised when a directory operation (such as :func:`os.listdir`) is requested |
| on something which is not a directory. |
| Corresponds to :c:data:`errno` ``ENOTDIR``. |
| |
| .. exception:: PermissionError |
| |
| Raised when trying to run an operation without the adequate access |
| rights - for example filesystem permissions. |
| Corresponds to :c:data:`errno` ``EACCES`` and ``EPERM``. |
| |
| .. exception:: ProcessLookupError |
| |
| Raised when a given process doesn't exist. |
| Corresponds to :c:data:`errno` ``ESRCH``. |
| |
| .. exception:: TimeoutError |
| |
| Raised when a system function timed out at the system level. |
| Corresponds to :c:data:`errno` ``ETIMEDOUT``. |
| |
| .. versionadded:: 3.3 |
| All the above :exc:`OSError` subclasses were added. |
| |
| |
| .. seealso:: |
| |
| :pep:`3151` - Reworking the OS and IO exception hierarchy |
| |
| |
| Warnings |
| -------- |
| |
| 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:`bytearray`. |
| |
| |
| .. 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 |