6. 内建异常

异常应该是类对象 (class objects)。异常定义在 exceptions 模块中。该模块从不需要被显式地导入:这些异常在内建的命名空间中有提供,就和 exceptions 模块一样。

对于类异常,如果在 try 语句的 except 从句中提到一个类,该从句还会处理任何从那个类派生的异常类(不是自 派生的异常类)。通过子类化得到的两个不相关的异常类永远不会相等,即便它们具有相同的名称。

下面列出的异常可以通过解释器或内建函数生成。除了提到的那些地方,它们还有“关联值 (associated value)”指示错误的详细的原因。它可能是一个字符串或一个包含几项信息的元组(例如,错误码和解释代码的字符串)。关联值是 raise 语句的第二个参数。如果异常类派生自标准的 BaseException 基类,关联值会以异常实例的 args 属性呈现。

用户代码可以引发内建异常。这可以用来测试异常处理程序,或报告一个错误情形,“就像”解释器在这种情况下引起的相同异常;但要注意,没有办法能阻止用户代码引发一个不恰当的错误。

内建异常类可以创建子类,从而定义新的异常;程序员应该从 Exception 类或它的一个子类,而不是从 BaseException 派生新的异常。有关定义异常的详细信息可以查阅《Python 教程》中的 用户定义的异常 一节。

下面的异常,只用作其它异常的基类。

exception BaseException

所有内建的异常的基类。它并不意味用户定义的类应该直接继承它(因此,请使用 Exception)。如果在该类的一个实例上调用 str()unicode(),则返回对该实例的参数表示,当没有参数时,则返回空字符串。

版本 2.5 新增。

args

异常构造函数的参数元组。有些内建异常(如 IOError)期望一定数量的参数并为此元组的元素分配特殊的含义,而其它异常的调用通常只需要一个单一的字符串来提供一条错误消息。

exception Exception

所有内建的、非系统退出的异常,都是从该类派生的。此外,应该从该类派生所有用户定义的异常。

版本 2.5 变更:改从 BaseException 继承。

exception StandardError

StopIteration, GeneratorExit, KeyboardInterruptSystemExit 以外的所有内建异常的基类。StandardError 本身继承自 Exception

exception ArithmeticError

各种算术错误引发的内建异常的基类:OverflowError, ZeroDivisionError, FloatingPointError

exception BufferError

buffer 相关的操作无法执行时引发。

exception LookupError

当用于映射或序列的键或索引无效时引发的异常的基类:IndexError, KeyError可以直接通过 codecs.lookup() 引发。

exception EnvironmentError

Python 系统以外发生的异常的基类:IOError, OSError当用二元组创建这种类型的异常时,元组的第一项可以通过实例的 errno 属性访问(它被假设为一个错误编号),第二项可以通过 strerror 属性访问(它通常与错误消息关联)。元组本身也是可以用在 args 属性上的。

版本 1.5.2 新增。

当一个 EnvironmentError 异常以三元组实例化时,前两项的访问和上面一样,第三项可以通过 filename 属性访问。然而,为了保持向后兼容性,args 属性仅包含一个二元组,用来放置前两个构造函数参数。

当该异常不以 3 个参数创建时,filename 属性为 None当异常实例不以 2 个或 3 个参数创建时,errnostrerror 属性也为 None在最后一种情况下,args 以一个元组的形式,包含逐字的构造函数参数。

以下是会实际被引发的异常。

exception AssertionError

assert 语句失败时引发。

exception AttributeError

当属性引用(参见 属性引用)或赋值失败时引发。(当对象根本不支持属性引用或属性赋值时,将引发 TypeError。)

exception EOFError

当内建函数 input()raw_input() 的其中之一,在触及文件结尾 (EOF) 情形,而没有读取到任何数据时引发。(注:file.read()file.readline() 方法在触及 EOF 时,返回一个空字符串。)

exception FloatingPointError

当浮点数操作失败时引发。该异常总是被定义的,但仅能当 Python 用 --with-fpectl 选项配置时,或当 pyconfig.h 文件中定义了 WANT_SIGFPE_HANDLER 符号时引发。

exception GeneratorExit

当调用一个 generator 对象的 close() 方法时引发。它直接继承自 BaseException 而不是 StandardError ,因为从技术上讲,它不算是一个错误。

版本 2.5 新增。

版本 2.6 变更:改从 BaseException 继承。

exception IOError

当一个 I/O 操作(如一条 print 语句,调用内建 open() 函数,或者调用一个文件对象的方法),由于 I/O 相关原因导致失败时,即“未找到文件”或“磁盘已满”时引发。

此类是从 EnvironmentError 派生的。异常实例属性请参阅上文讨论的详细信息。

版本 2.6 变更:改让 socket.error 使用本异常作为基类。

exception ImportError

import 语句无法找到模块定义,或者当 from ... import 语句未能找到要导入的名称时引发。

exception IndexError

当序列下标超出取值范围时引发。(切片索引会被静默地截取到允许范围内;如果索引不是一个普通整数,则引发 TypeError。)

exception KeyError

当在现有键的集合中找不到映射的(字典)键时引发。

exception KeyboardInterrupt

当用户按下中断键(通常是 Ctrl-CDelete)时引发。执行期间,会定期检查中断。当内建函数input()raw_input() 在等待输入时,键入中断键,也会引发本异常。该异常继承自 BaseException ,因此不会被 Exception 的捕获代码意外捕获,以防止解释器退出。

版本 2.5 变更:改从 BaseException 继承。

exception MemoryError

当一个操作将内存耗尽,但情况仍可挽救时(通过删除某些对象)时引发。关联值是一个字符串,它指示哪种(内部)操作耗尽了内存。请注意,由于底层内存管理体系结构是使用 C 的 malloc() 函数,因此,解释器不可能总是从这种情况完全恢复;它仍然会引发异常,以便让堆栈回溯能够打印出来,防止因程序跑飞 (a run-away program) 导致问题发生。

exception NameError

当找不到本地或全局名称时引发。这仅适用于不合格的名称。关联值是一条错误消息,其中包括找不到的名称。

exception NotImplementedError

此异常是从 RuntimeError 派生的。当用户定义基类需要派生类重写方法时,抽象方法会引发该异常。

版本 1.5.2 新增。

exception OSError

此异常是从 EnvironmentError 派生的。当一个函数返回系统相关的错误(不是由于非法参数类型或其他偶然导致的错误)时引发。属性 errno 是一条来自 errno 的数字错误代码,属性 strerror 则是相应的字符串,会由 C 函数 perror() 打印出来。请参阅 errno 模块,其中包含由底层操作系统定义的错误代码的名称。

对于涉及到文件系统路径的异常(如 chdir()unlink()),异常实例将含有第三个属性,filename,它是传递给函数的文件名。

版本 1.5.2 新增。

exception OverflowError

当要表示算术运算的结果太大时引发。长整型数字不会导致该异常,(长整型数字会引发 MemoryError 而不会放弃);普通整型数字也不会导致该异常,作为替代,它会返回一个长整型。由于 C 缺乏标准浮点异常处理,因此,不会检查大部分浮点运算。

exception ReferenceError

当用一个由 weakref.proxy() 函数创建的弱引用代理,去访问引用者的属性,而该引用者已经被垃圾回收时,会引发此异常。更多有关弱引用的信息,请参阅 weakref 模块。

版本 2.2 新增:之前称为 weakref.ReferenceError 异常。

exception RuntimeError

当检出错误不属于任何其它类别时引发。关联值是一个字符串,它指示到底什么地方出错了。

exception StopIteration

当一个 iteratornext() 方法发出信号,表示没有更多的值时引发。派生自 Exception,而不是 StandardError,因为在其正常程序中,并不认为它是一个错误。

版本 2.2 新增。

exception SyntaxError

当解析器遇到语法错误时引发。这会发生在 import 语句中,exec 语句中,调用内建函数 eval()input() 时,或者在读取初始脚本、标准输入(可交互)时。

该类的实例具有更容易访问相关细节的 文件名 (filename)行号 (lineno)偏移 (offset)文本 (text) 属性。向内建函数 str() 传入异常实例,仅会返回错误消息。

exception IndentationError

与不正确的缩进相关的语法错误的基类。这是 SyntaxError 的一个子类。

exception TabError

当缩进中包含对制表符和空格的混用时引发。这是 IndentationError 的一个子类。

exception SystemError

当解释器发现内部错误,但情况并没有看起来那么严重,不至于到要放弃所有希望的地步,此时会引发本异常。关联值是一个字符串,它(用底层术语)指示什么出错了。

您应把这个异常报告给您的 Python 解释器的作者或维护者。请务必报告您使用的 Python 解释器版本(sys.version;版本号在 Python 交互会话开始时也会被打印出来),确切的错误消息(异常的关联值),以及错误出发的程序源码(如果您方便提供的话)。

exception SystemExit

sys.exit() 函数引发此异常。如果不处理这个异常,Python 解释器退出;并且不打印堆栈回溯 (stack traceback)。如果关联值是一个普通整数,它指定系统退出状态(传递给 C 的 exit() 函数);如果它是 None,则退出状态为 0;如果它有另一种类型(比如一个字符串),该对象的值会被打印,并且退出状态是 1。

实例有一个 code 属性,它被设定为一条提议的退出码,或错误消息(默认为 None)。此外,该异常直接继承自 BaseException 而不是 StandardError,因为从技术上讲,它不算是一个错误。

sys.exit() 的调用会被转译成异常,以便执行清理处理程序(try 语句的 finally 从句),因此,调试器会执行脚本,不必冒失去控制的风险。如果绝对需要程序立即退出(例如,在调用 os.fork() 后的子进程中),可以使用 os._exit() 函数。

该异常继承自 BaseException 而不是 StandardErrorException,因此不会被 Exception 捕获代码意外捕获。这允许将异常正确传播起来并导致解释器退出。

版本 2.5 变更:改从 BaseException 继承。

exception TypeError

当操作或函数应用于不合适类型的对象时引发。关联值是字符串,它提供有关类型不匹配的详细信息。

exception UnboundLocalError

当引用函数或方法局部变量,但变量没有绑定值时引发。这是 NameError 的一个子类。

版本 2.0 新增。

exception UnicodeError

当有关 Unicode 编码或解码错误出现时引发。它是 ValueError 的一个子类。

UnicodeError 具有描述编码或解码错误的属性。例如,err.object[err.start:err.end] 给出了导致解码器失败的特定的无效输入。

encoding

引发错误的编码名称。

reason

一个字符串,它描述特定的解码器错误。

object

解码器试图进行编码或解码的对象。

start

object 的第一个索引中数据无效。

end

object 的最后一个索引中数据无效。

版本 2.0 新增。

exception UnicodeEncodeError

当编码过程中出现的一个 Unicode 相关的错误时引发。它是 UnicodeError 的一个子类。

版本 2.3 新增。

exception UnicodeDecodeError

当解码过程中出现的一个 Unicode 相关的错误时引发。它是 UnicodeError 的一个子类。

版本 2.3 新增。

exception UnicodeTranslateError

当翻译过程中出现的一个 Unicode 相关的错误时引发。它是 UnicodeError 的一个子类。

版本 2.3 新增。

exception ValueError

当内建操作或函数,接收到类型正确,但值不正确的参数,而且这种情况不能用诸如 IndexError 这样的更精确的异常进行描述时引发。

exception VMSError

仅在 VMS 上可用。当发生 VMS 特定错误时引发。

exception WindowsError

当 Windows 特定的错误发生时,或者当错误号码与 errno 值不对应时引发。Winerrorstrerror 的值创建自 Windows 平台 API 中的 GetLastError() 函数和 FormatMessage() 函数的返回值。Errno 值将 winerror 值映射到相应的 errno.h 值。这是 OSError 的一个子类。

版本 2.0 新增。

版本 2.5 变更:之前的版本把 GetLastError() 的代码放在 errno 之中。

exception ZeroDivisionError

当除法或取模运算的第 2 个参数为 0 时引发。关联值是一个字符串,它指出操作数的类型和运算符。

以下异常作为警告类别使用;详细信息请参阅 warnings 模块。

exception Warning

警告类别基类。

exception UserWarning

用户代码生成警告基类。

exception DeprecationWarning

弃用特性警告基类。

exception PendingDeprecationWarning

将来会被弃用特性的警告基类。

exception SyntaxWarning

可疑句法警告基类。

exception RuntimeWarning

可疑 Runtime 行为警告基类。

exception FutureWarning

将来会改变语义结构的警告基类。

exception ImportWarning

可能弄错模块导入警告基类。

版本 2.5 新增。

exception UnicodeWarning

Unicode 相关的警告基类。

版本 2.5 新增。

6.1. 异常的层次结构

内建异常的类层次结构是:

BaseException
 +-- SystemExit
 +-- KeyboardInterrupt
 +-- GeneratorExit
 +-- Exception
      +-- StopIteration
      +-- StandardError
      |    +-- BufferError
      |    +-- 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
	   +-- BytesWarning