diff options
Diffstat (limited to 'Doc/library/exceptions.rst')
| -rw-r--r-- | Doc/library/exceptions.rst | 475 |
1 files changed, 475 insertions, 0 deletions
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst new file mode 100644 index 0000000..d6a64fc --- /dev/null +++ b/Doc/library/exceptions.rst @@ -0,0 +1,475 @@ +.. _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 emptry + 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:: 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 or assignment fails. (When an object does + not support attribute references or attribute assignments at all, + :exc:`TypeError` is raised.) + + .. % xref to attribute reference? + + +.. exception:: EOFError + + Raised when attempting to read beyond the end of a file. (N.B.: the :meth:`read` + and :meth:`readline` methods of file objects return an empty string when they + hit EOF.) + + .. % 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 + + Raise when a generator's :meth:`close` method is called. + + .. versionadded:: 2.5 + + .. versionchanged:: 3.0 + Changed to inherit from Exception instead of StandardError. + + +.. 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". + + .. % XXXJH xrefs here + + 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. + + .. % 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.) + + .. % XXXJH xref to sequences + + +.. exception:: KeyError + + Raised when a mapping (dictionary) key is not found in the set of existing keys. + + .. % XXXJH 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. + + .. % 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 + 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 + + This class is derived from :exc:`EnvironmentError` and is used primarily as the + :mod:`os` module's ``os.error`` exception. See :exc:`EnvironmentError` above for + a description of the possible associated values. + + .. % xref for os module + + .. 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). Because of the lack of standardization of + floating point exception handling in C, most floating point operations also + aren't checked. For plain integers, all operations that can overflow are + 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. + + .. 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 builtin :func:`next` and an iterator's :meth:`__next__` method to + signal that there are no further values. + + .. versionadded:: 2.2 + + .. versionchanged:: 3.0 + Changed to inherit from Exception instead of StandardError. + + +.. 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). + + .. % 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 + + 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. + + .. % 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:`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. + + .. 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:: 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 + +The class hierarchy for built-in exceptions is: + + +.. literalinclude:: ../../Lib/test/exception_hierarchy.txt |