/Doc/library/exceptions.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 486 lines · 298 code · 188 blank · 0 comment · 0 complexity · d51580f3bd34d0ec2dd8ca951564dd9b MD5 · raw file
- .. _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.
- .. 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
- 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
- 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
- :keyword:`raise` statement. If the exception class is derived from the standard
- root class :exc:`BaseException`, the associated value is present as the
- exception instance's :attr:`args` 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
- defining exceptions is available in the Python Tutorial under
- :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
- representation of the argument(s) to the instance are returned or the empty
- string when there were no arguments. All arguments are stored in :attr:`args`
- as a tuple.
- .. 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.
- .. versionchanged:: 2.5
- Changed to inherit from :exc:`BaseException`.
- .. exception:: StandardError
- The base class for all built-in exceptions except :exc:`StopIteration`,
- :exc:`GeneratorExit`, :exc:`KeyboardInterrupt` and :exc:`SystemExit`.
- :exc:`StandardError` itself is derived from :exc:`Exception`.
- .. exception:: ArithmeticError
- The base class for those built-in exceptions that are raised for various
- arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`,
- :exc:`FloatingPointError`.
- .. 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:`sys.setdefaultencoding`.
- .. 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.
- .. versionadded:: 1.5.2
- 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 actually 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
- :option:`--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:`StandardError` since
- it is technically not an error.
- .. versionadded:: 2.5
- .. 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".
- This class is derived from :exc:`EnvironmentError`. See the discussion above
- for more information on exception instance attributes.
- .. 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.
- .. 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.)
- .. 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.
- 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.
- .. 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
- 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 :cfunc:`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.
- .. versionadded:: 1.5.2
- .. 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 :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
- :exc:`MemoryError` than give up) and for most operations with plain integers,
- which return a long integer instead. 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.
- .. versionadded:: 2.2
- Previously known as the :exc:`weakref.ReferenceError` exception.
- .. 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 an :term:`iterator`\'s :meth:`next` method to signal that there are
- no further values. This is derived from :exc:`Exception` rather than
- :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).
- 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
- 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 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.
- 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
- 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:`StandardError`
- or :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.
- .. versionchanged:: 2.5
- Changed to inherit from :exc:`BaseException`.
- .. 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`.
- .. versionadded:: 2.0
- .. exception:: UnicodeError
- Raised when a Unicode-related encoding or decoding error occurs. It is a
- subclass of :exc:`ValueError`.
- .. versionadded:: 2.0
- .. exception:: UnicodeEncodeError
- Raised when a Unicode-related error occurs during encoding. It is a subclass of
- :exc:`UnicodeError`.
- .. versionadded:: 2.3
- .. exception:: UnicodeDecodeError
- Raised when a Unicode-related error occurs during decoding. It is a subclass of
- :exc:`UnicodeError`.
- .. versionadded:: 2.3
- .. exception:: UnicodeTranslateError
- Raised when a Unicode-related error occurs during translating. It is a subclass
- of :exc:`UnicodeError`.
- .. versionadded:: 2.3
- .. 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 :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`.
- .. versionadded:: 2.0
- .. versionchanged:: 2.5
- Previous versions put the :cfunc:`GetLastError` codes into :attr:`errno`.
- .. 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.
- .. versionadded:: 2.5
- .. exception:: UnicodeWarning
- Base class for warnings related to Unicode.
- .. versionadded:: 2.5
- Exception hierarchy
- -------------------
- The class hierarchy for built-in exceptions is:
- .. literalinclude:: ../../Lib/test/exception_hierarchy.txt