mirror of
https://github.com/python/cpython.git
synced 2024-12-02 14:24:12 +08:00
fa0d703433
svn+ssh://pythondev@svn.python.org/python/trunk ........ r72506 | vinay.sajip | 2009-05-09 07:07:17 -0500 (Sat, 09 May 2009) | 1 line Issue #5971: StreamHandler.handleError now swallows IOErrors which occur when trying to print a traceback. ........ r72525 | benjamin.peterson | 2009-05-09 20:38:02 -0500 (Sat, 09 May 2009) | 1 line close file explicitly ........ r72526 | benjamin.peterson | 2009-05-09 21:29:00 -0500 (Sat, 09 May 2009) | 1 line make sure files are closed using the with statement ........ r72551 | benjamin.peterson | 2009-05-10 09:16:47 -0500 (Sun, 10 May 2009) | 1 line use isinstance ........ r72558 | benjamin.peterson | 2009-05-10 18:52:09 -0500 (Sun, 10 May 2009) | 1 line sys.setdefaultencoding() strikes me as a bad example ........ r72616 | benjamin.peterson | 2009-05-13 19:33:10 -0500 (Wed, 13 May 2009) | 1 line importlib.import_module is better these days ........ r72654 | benjamin.peterson | 2009-05-14 17:37:49 -0500 (Thu, 14 May 2009) | 1 line prevent refleaks from threads ........ r72655 | benjamin.peterson | 2009-05-14 17:40:34 -0500 (Thu, 14 May 2009) | 1 line a useful decorator for cleaning up threads ........ r72689 | benjamin.peterson | 2009-05-16 13:44:34 -0500 (Sat, 16 May 2009) | 1 line use skipTest() ........ r72745 | benjamin.peterson | 2009-05-17 09:16:29 -0500 (Sun, 17 May 2009) | 1 line ignore .rst files in sphinx its self ........ r72750 | benjamin.peterson | 2009-05-17 11:59:27 -0500 (Sun, 17 May 2009) | 1 line chop off slash ........ r72802 | georg.brandl | 2009-05-20 13:35:27 -0500 (Wed, 20 May 2009) | 1 line #6051: refer to email examples for better way to construct email messages. ........ r72812 | michael.foord | 2009-05-21 17:57:02 -0500 (Thu, 21 May 2009) | 1 line Rename TestCase._result to _resultForDoCleanups to avoid potential clashes in TestCase subclasses. Issue 6072. ........ r72822 | georg.brandl | 2009-05-22 04:33:25 -0500 (Fri, 22 May 2009) | 1 line #6084: fix example. ........ r72824 | georg.brandl | 2009-05-22 04:43:17 -0500 (Fri, 22 May 2009) | 1 line Fix references to file-related functions and methods (os.* vs file.*). ........ r72826 | georg.brandl | 2009-05-22 04:49:42 -0500 (Fri, 22 May 2009) | 1 line Fix confusing wording. ........ r72827 | georg.brandl | 2009-05-22 04:50:30 -0500 (Fri, 22 May 2009) | 1 line s/use/call/ ........ r72833 | georg.brandl | 2009-05-22 12:00:17 -0500 (Fri, 22 May 2009) | 1 line #6078: _warnings is a builtin module and has no standard init_warnings function. ........ r72876 | benjamin.peterson | 2009-05-23 15:59:09 -0500 (Sat, 23 May 2009) | 1 line remove mention of old ctypes version ........ r72890 | gregory.p.smith | 2009-05-24 13:00:13 -0500 (Sun, 24 May 2009) | 2 lines add a versionadded tag for set_tunnel ........ r72923 | michael.foord | 2009-05-25 15:36:56 -0500 (Mon, 25 May 2009) | 1 line Make assertSequenceEqual error messages less cryptic, particularly for nested sequences. ........ r72946 | ronald.oussoren | 2009-05-26 13:44:48 -0500 (Tue, 26 May 2009) | 2 lines Fixes issue 6110 ........ r73026 | r.david.murray | 2009-05-29 14:30:27 -0500 (Fri, 29 May 2009) | 3 lines Issue 6141: document that the first item of args is still the command name even when executable is specified. ........ r73042 | benjamin.peterson | 2009-05-29 22:10:52 -0500 (Fri, 29 May 2009) | 1 line no fdatasync on macos ........ r73045 | georg.brandl | 2009-05-30 02:26:04 -0500 (Sat, 30 May 2009) | 1 line #6146: fix markup bug. ........ r73047 | georg.brandl | 2009-05-30 05:33:23 -0500 (Sat, 30 May 2009) | 1 line Fix some more small markup problems. ........ r73065 | antoine.pitrou | 2009-05-30 16:39:25 -0500 (Sat, 30 May 2009) | 3 lines The test for #5330 wasn't correct. ........ r73068 | antoine.pitrou | 2009-05-30 16:45:40 -0500 (Sat, 30 May 2009) | 3 lines Update ACKS ........ r73069 | benjamin.peterson | 2009-05-30 19:42:42 -0500 (Sat, 30 May 2009) | 1 line fix signature ........
429 lines
15 KiB
ReStructuredText
429 lines
15 KiB
ReStructuredText
.. _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.
|
|
|
|
.. XXX document with_traceback()
|
|
|
|
.. 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.
|
|
|
|
|
|
.. 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:: 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 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:`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 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 :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.
|
|
|
|
|
|
.. 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.
|
|
|
|
|
|
.. 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 builtin :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:: 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 :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:`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 :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`.
|
|
|
|
|
|
.. 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`.
|
|
|
|
|
|
The class hierarchy for built-in exceptions is:
|
|
|
|
.. literalinclude:: ../../Lib/test/exception_hierarchy.txt
|