n | .. _bltin-exceptions: |
| |
| Built-in Exceptions |
| =================== |
| |
| .. module:: exceptions |
| :synopsis: Standard exception classes. |
| |
| |
| Exceptions should be class objects. The exceptions are defined in the module |
| :mod:`exceptions`. This module never needs to be imported explicitly: the |
| exceptions are provided in the built-in namespace as well as the |
| :mod:`exceptions` module. |
n | |
| .. note:: |
| |
| In past versions of Python string exceptions were supported. In Python 1.5 and |
| newer versions, all standard exceptions have been converted to class objects and |
| users are encouraged to do the same. String exceptions will raise a |
| ``DeprecationWarning`` in Python 2.5 and newer. In future versions, support for |
| string exceptions will be removed. |
| |
| Two distinct string objects with the same value are considered different |
| exceptions. This is done to force programmers to use exception names rather |
| than their string value when specifying exception handlers. The string value of |
| all built-in exceptions is their name, but this is not a requirement for user- |
| defined exceptions or exceptions defined by library modules. |
| |
| .. index:: |
| statement: try |
| statement: except |
| |
| For class exceptions, 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 |
| |
| .. 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 |
| containing several items of information (e.g., an error code and a string |
| explaining the code). The associated value is the second argument to the |
n | :keyword:`raise` statement. For string exceptions, the associated value itself |
n | :keyword:`raise` statement. If the exception class is derived from the standard |
| will be stored in the variable named as the second argument of the |
| :keyword:`except` clause (if any). For class exceptions, that variable receives |
| the exception instance. If the exception class is derived from the standard |
| root class :exc:`BaseException`, the associated value is present as the |
n | exception instance's :attr:`args` attribute. If there is a single argument (as |
n | exception instance's :attr:`args` attribute. |
| is preferred), it is bound to the :attr:`message` attribute. |
| |
| 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 |
n | defining exceptions is available in the Python Tutorial (XXX reference: |
n | defining exceptions is available in the Python Tutorial under |
| ../tut/tut.html) under the heading "User-defined Exceptions." |
| :ref:`tut-userexceptions`. |
| |
| The following exceptions are only used 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` or :func:`unicode` is called on an instance of this class, the |
n | representation of the argument(s) to the instance are returned or the emptry |
n | representation of the argument(s) to the instance are returned or the empty |
| string when there were no arguments. If only a single argument is passed in, it |
| string when there were no arguments. All arguments are stored in :attr:`args` |
| is stored in the :attr:`message` attribute. If more than one argument is passed |
| as a tuple. |
| in, :attr:`message` is set to the empty string. These semantics are meant to |
| reflect the fact that :attr:`message` is to store a text message explaining why |
| the exception had been raised. If more data needs to be attached to the |
| exception, attach it through arbitrary attributes on the instance. All |
| arguments are also stored in :attr:`args` as a tuple, but it will eventually be |
| deprecated and thus its use is discouraged. |
| |
| .. versionadded:: 2.5 |
| |
| |
| .. 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. |
| |
| .. index:: statement: assert |
| |
| Raised when an :keyword:`assert` statement fails. |
| |
| |
| .. exception:: AttributeError |
| |
n | Raised when an attribute reference or assignment fails. (When an object does |
n | Raised when an attribute reference (see :ref:`attribute-references`) or |
| not support attribute references or attribute assignments at all, |
| assignment fails. (When an object does not support attribute references or |
| :exc:`TypeError` is raised.) |
| attribute assignments at all, :exc:`TypeError` is raised.) |
| |
| .. % xref to attribute reference? |
| |
| |
| .. 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 |
n | :meth:`read` and :meth:`readline` methods of file objects return an empty string |
n | :meth:`file.read` and :meth:`file.readline` methods return an empty string |
| when they hit EOF.) |
n | |
| .. % XXXJH xrefs here |
| .. % XXXJH xrefs here |
| |
| |
| .. 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 |
| :option:`--with-fpectl` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is |
| defined in the :file:`pyconfig.h` file. |
| |
| |
| .. exception:: GeneratorExit |
| |
n | Raise when a generator's :meth:`close` method is called. It directly inherits |
n | Raise when a :term:`generator`\'s :meth:`close` method is called. It |
| from :exc:`Exception` instead of :exc:`StandardError` since it is technically |
| directly inherits from :exc:`BaseException` instead of :exc:`StandardError` since |
| not an error. |
| it is technically not an error. |
| |
| .. versionadded:: 2.5 |
| |
n | .. versionchanged:: 2.6 |
| Changed to inherit from :exc:`BaseException`. |
| |
| .. exception:: IOError |
| |
| Raised when an I/O operation (such as a :keyword:`print` statement, the built-in |
| :func:`open` function or a method of a file object) fails for an I/O-related |
| reason, e.g., "file not found" or "disk full". |
| |
n | .. % XXXJH xrefs here |
| |
| This class is derived from :exc:`EnvironmentError`. See the discussion above |
| for more information on exception instance attributes. |
| |
n | .. versionchanged:: 2.6 |
| Changed :exc:`socket.error` to use this as a base class. |
| |
| |
| .. 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. |
n | |
| .. % XXXJH xref to import statement? |
| |
| |
| .. 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 a plain integer, |
| :exc:`TypeError` is raised.) |
| |
n | .. % XXXJH xref to sequences |
n | .. XXX xref to sequences |
| |
| |
| .. exception:: KeyError |
| |
| Raised when a mapping (dictionary) key is not found in the set of existing keys. |
| |
n | .. % XXXJH xref to mapping objects? |
n | .. 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. |
| Interrupts typed when a built-in function :func:`input` or :func:`raw_input` is |
| waiting for input also raise this exception. 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. |
n | |
| .. % XXX(hylton) xrefs here |
| |
| .. versionchanged:: 2.5 |
| Changed to inherit from :exc:`BaseException`. |
| |
| |
| .. exception:: MemoryError |
| |
| Raised when an operation runs out of memory but the situation may still be |
| classes, abstract methods should raise this exception when they require derived |
| classes to override the method. |
| |
| .. versionadded:: 1.5.2 |
| |
| |
| .. exception:: OSError |
| |
n | This class is derived from :exc:`EnvironmentError` and is used primarily as the |
n | .. index:: module: errno |
| :mod:`os` module's ``os.error`` exception. See :exc:`EnvironmentError` above for |
| a description of the possible associated values. |
| |
n | .. % xref for os module |
n | 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 :cdata:`errno`, and the :attr:`strerror` attribute is the |
| corresponding string, as would be printed by the C function :cfunc:`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. |
| |
| .. versionadded:: 1.5.2 |
| |
| |
| .. exception:: OverflowError |
| |
| Raised when the result of an arithmetic operation is too large to be |
| represented. This cannot occur for long integers (which would rather raise |
n | :exc:`MemoryError` than give up). Because of the lack of standardization of |
n | :exc:`MemoryError` than give up) and for most operations with plain integers, |
| which return a long integer instead. Because of the lack of standardization |
| floating point exception handling in C, most floating point operations also |
| of floating point exception handling in C, most floating point operations |
| aren't checked. For plain integers, all operations that can overflow are |
| also aren't checked. |
| checked except left shift, where typical applications prefer to drop bits than |
| raise an exception. |
| |
| .. % XXXJH reference to long's and/or int's? |
| |
| |
| .. 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. |
| 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 |
| |
n | Raised by an iterator's :meth:`next` method to signal that there are no further |
n | Raised by an :term:`iterator`\'s :meth:`next` method to signal that there are |
| values. This is derived from :exc:`Exception` rather than :exc:`StandardError`, |
| no further values. This is derived from :exc:`Exception` rather than |
| since this is not considered an error in its normal application. |
| :exc:`StandardError`, since this is not considered an error in its normal |
| application. |
| |
| .. versionadded:: 2.2 |
| |
| |
| .. exception:: SyntaxError |
| |
| Raised when the parser encounters a syntax error. This may occur in an |
| :keyword:`import` statement, in an :keyword:`exec` statement, in a call to the |
| built-in function :func:`eval` or :func:`input`, or when reading the initial |
| script or standard input (also interactively). |
n | |
| .. % XXXJH xref to these functions? |
| |
| 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:: SystemError |
| |
| |
| 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 a plain integer, it specifies the system exit status (passed |
| to C's :cfunc:`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. |
| |
n | .. % XXX(hylton) xref to module sys? |
| |
| 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:`StandardError`, 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 |
| |
| .. 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`. |
| |
| |
n | .. 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 :cdata:`errno` value. The :attr:`winerror` and |
| :attr:`strerror` values are created from the return values of the |
| :cfunc:`GetLastError` and :cfunc:`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`. |