Movatterモバイル変換

2.3 Built-in Exceptions

Exceptions should be class objects. The exceptions are defined in the moduleexceptions. Thismodule never needs to be imported explicitly: the exceptions areprovided in the built-in namespace as well as theexceptionsmodule.

Note:In past versions of Python string exceptions were supported. InPython 1.5 and newer versions, all standard exceptions have beenconverted to class objects and users are encouraged to do the same.String exceptions will raise aDeprecationWarning in Python 2.5 andnewer.In future versions, support for string exceptions will be removed.

Two distinct string objects with the same value are considered differentexceptions. This is done to force programmers to use exception namesrather than their string value when specifying exception handlers.The string value of all built-in exceptions is their name, but this isnot a requirement for user-defined exceptions or exceptions defined bylibrary modules.

For class exceptions, in atry statement withanexcept clause that mentions a particularclass, that clause also handles any exception classes derived fromthat class (but not exception classes from whichit isderived). Two exception classes that are not related via subclassingare never equivalent, even if they have the same name.

The built-in exceptions listed below can be generated by theinterpreter or built-in functions. Except where mentioned, they havean ``associated value'' indicating the detailed cause of the error.This may be a string or a tuple containing several items ofinformation (e.g., an error code and a string explaining the code).The associated value is the second argument to theraise statement. For string exceptions, theassociated value itself will be stored in the variable named as thesecond argument of theexcept clause (if any). For classexceptions, that variable receives the exception instance. If theexception class is derived from the standard root classBaseException, the associated value is present as theexception instance'sargs attribute. If there is a single argument(as is preferred), it is bound to themessage attribute.

User code can raise built-in exceptions. This can be used to test anexception handler or to report an error condition ``just like'' thesituation in which the interpreter raises the same exception; butbeware that there is nothing to prevent user code from raising aninappropriate error.

The built-in exception classes can be sub-classed to define newexceptions; programmers are encouraged to at least derive newexceptions from theException class and notBaseException. Moreinformation on defining exceptions is available in thePython Tutorial under the heading``User-defined Exceptions.''

The following exceptions are only used as base classes for otherexceptions.

exception BaseException: The base class for all built-in exceptions. It is not meant to be directlyinherited by user-defined classes (for that useException). Ifstr() orunicode() is called on an instance of thisclass, the representation of the argument(s) to the instance are returned orthe emptry string when there were no arguments. If only a single argument ispassed in, it is stored in themessage attribute. If more than oneargument is passed in,message is set to the empty string. Thesesemantics are meant to reflect the fact thatmessage is to store atext message explaining why the exception had been raised. If more data needsto be attached to the exception, attach it through arbitrary attributes on theinstance. All arguments are also stored inargs as a tuple, but it willeventually be deprecated and thus its use is discouraged.New in version 2.5.

exception Exception: All built-in, non-system-exiting exceptions are derivedfrom this class. All user-defined exceptions should also be derivedfrom this class.Changed in version 2.5:Changed to inherit fromBaseException.

exception StandardError: The base class for all built-in exceptions exceptStopIteration,GeneratorExit,KeyboardInterrupt andSystemExit.StandardError itself is derived fromException.

exception ArithmeticError: The base class for those built-in exceptions that are raised forvarious arithmetic errors:OverflowError,ZeroDivisionError,FloatingPointError.

exception LookupError: The base class for the exceptions that are raised when a key orindex used on a mapping or sequence is invalid:IndexError,KeyError. This can be raised directly bysys.setdefaultencoding().

exception EnvironmentError

The base class for exceptions thatcan occur outside the Python system:IOError,OSError. When exceptions of this type are created with a2-tuple, the first item is available on the instance'serrnoattribute (it is assumed to be an error number), and the second itemis available on thestrerror attribute (it is usually theassociated error message). The tuple itself is also available on theargs attribute.New in version 1.5.2.

When anEnvironmentError exception is instantiated with a3-tuple, the first two items are available as above, while the thirditem is available on thefilename attribute. However, forbackwards compatibility, theargs attribute contains only a2-tuple of the first two constructor arguments.

Thefilename attribute isNone when this exception iscreated with other than 3 arguments. Theerrno andstrerror attributes are alsoNone when the instance wascreated with other than 2 or 3 arguments. In this last case,args contains the verbatim constructor arguments as a tuple.

The following exceptions are the exceptions that are actually raised.

exception AssertionError: Raised when anassert 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,TypeError is raised.)

exception EOFError: Raised when one of the built-in functions (input() orraw_input()) hits an end-of-file condition (EOF) without reading any data.(N.B.: theread() andreadline() methods of file objects 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 theWANT_SIGFPE_HANDLER symbol is defined in thepyconfig.h file.

exception GeneratorExit: Raise when a generator'sclose() method is called. It directly inherits fromException instead ofStandardError since it is technically not an error.New in version 2.5.

exception IOError: Raised when an I/O operation (such as aprint statement, the built-inopen() 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 fromEnvironmentError. See the discussion above for more information on exception instance attributes.

exception ImportError: Raised when animport statement fails to find the module definition or when afrom ... 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,TypeError is raised.)

exception KeyError: Raised when a mapping (dictionary) key is not found in the set of existing keys.

exception KeyboardInterrupt: Raised when the user hits the interrupt key (normallyControl-C orDelete). During execution, a check for interrupts is made regularly.Interrupts typed when a built-in functioninput() orraw_input() is waiting for input also raise this exception. The exception inherits fromBaseException so as to not be accidentally caught by code that catchesException and thus prevent the interpreter from exiting.Changed in version 2.5:Changed to inherit fromBaseException.

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'smalloc() 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 fromRuntimeError. In user defined base classes, abstract methods should raise this exception when they require derived classes to override the method.New in version 1.5.2.

exception OSError: This class is derived fromEnvironmentError and is used primarily as theos module'sos.error exception. SeeEnvironmentError above for a description of the possible associated values.New in version 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 raiseMemoryError 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.

exception ReferenceError: This exception is raised when a weak reference proxy, created by theweakref.proxy() function, is used to access an attribute of the referent after it has been garbage collected. For more information on weak references, see theweakref module.New in version 2.2:Previously known as theweakref.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 iterator'snext() method to signal that there are no further values. This is derived fromException rather thanStandardError, since this is not considered an error in its normal application.New in version 2.2.

exception SyntaxError: Raised when the parser encounters a syntax error. This may occur in animport statement, in anexec statement, in a call to the built-in functioneval() orinput(), or when reading the initial script or standard input (also interactively).
Instances of this class have attributesfilename,lineno,offset andtext for easier access to the details.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 thesys.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'sexit() function); if it isNone, 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 attributecode which is set to the proposed exit status or error message (defaulting toNone). Also, this exception derives directly fromBaseException and notStandardError, since it is not technically an error.

A call tosys.exit() is translated into an exception so that clean-up handlers (finally clauses oftry statements) can be executed, and so that a debugger can execute a script without running the risk of losing control. Theos._exit() function can be used if it is absolutely positively necessary to exit immediately (for example, in the child process after a call tofork()).

The exception inherits fromBaseException instead ofStandardError orException so that it is not accidentally caught by code that catchesException. This allows the exception to properly propagate up and cause the interpreter to exit.Changed in version 2.5:Changed to inherit fromBaseException.

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 ofNameError.New in version 2.0.

exception UnicodeError: Raised when a Unicode-related encoding or decoding error occurs. It is a subclass ofValueError.New in version 2.0.

exception UnicodeEncodeError: Raised when a Unicode-related error occurs during encoding. It is a subclass ofUnicodeError.New in version 2.3.

exception UnicodeDecodeError: Raised when a Unicode-related error occurs during decoding. It is a subclass ofUnicodeError.New in version 2.3.

exception UnicodeTranslateError: Raised when a Unicode-related error occurs during translating. It is a subclass ofUnicodeError.New in version 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 asIndexError.

exception WindowsError: Raised when a Windows-specific error occurs or when the error number does not correspond to anerrno value. Thewinerror andstrerror values are created from the return values of theGetLastError() andFormatMessage() functions from the Windows Platform API. Theerrno value maps thewinerror value to correspondingerrno.h values. This is a subclass ofOSError.New in version 2.0.Changed in version 2.5:Previous versions put theGetLastError()codes intoerrno.

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 thewarnings 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 semanticallyin the future.

exception ImportWarning: Base class for warnings about probable mistakes in module imports.New in version 2.5.

exception UnicodeWarning: Base class for warnings related to Unicode.New in version 2.5.

The class hierarchy for built-in exceptions is:

BaseException +-- SystemExit +-- KeyboardInterrupt +-- Exception      +-- GeneratorExit      +-- StopIteration      +-- StandardError      |    +-- ArithmeticError      |    |    +-- FloatingPointError      |    |    +-- OverflowError      |    |    +-- ZeroDivisionError      |    +-- AssertionError      |    +-- AttributeError      |    +-- EnvironmentError      |    |    +-- IOError      |    |    +-- OSError      |    |         +-- WindowsError (Windows)      |    |         +-- VMSError (VMS)      |    +-- EOFError      |    +-- ImportError      |    +-- LookupError      |    |    +-- IndexError      |    |    +-- KeyError      |    +-- MemoryError      |    +-- NameError      |    |    +-- UnboundLocalError      |    +-- ReferenceError      |    +-- RuntimeError      |    |    +-- NotImplementedError      |    +-- SyntaxError      |    |    +-- IndentationError      |    |         +-- TabError      |    +-- SystemError      |    +-- TypeError      |    +-- ValueError      |    |    +-- UnicodeError      |    |         +-- UnicodeDecodeError      |    |         +-- UnicodeEncodeError      |    |         +-- UnicodeTranslateError      +-- Warning           +-- DeprecationWarning           +-- PendingDeprecationWarning           +-- RuntimeWarning           +-- SyntaxWarning           +-- UserWarning           +-- FutureWarning   +-- ImportWarning   +-- UnicodeWarning

Download as text (original file name:../../Lib/test/exception_hierarchy.txt).

Release 2.5.2, documentation updated on 21st February, 2008.

SeeAbout this document... for information on suggesting changes.

[8]ページ先頭