6. 内置异常 — Python 文档

6. 内置异常

异常应该是类对象。 异常在模块 exceptions 中定义。 该模块永远不需要显式导入：异常在内置命名空间以及 exceptions 模块中提供。

对于类异常，在带有 except 子句的 try 语句中，该子句提到了一个特定的类，该子句还处理从该类派生的任何异常类（但不是从 [X224X ]it 是导出的）。 两个通过子类化不相关的异常类永远不会等价，即使它们具有相同的名称。

下面列出的内置异常可以由解释器或内置函数生成。 除非另有说明，否则它们都有一个“关联值”，指示错误的详细原因。 这可能是一个字符串或包含多项信息的元组（例如，错误代码和解释代码的字符串）。 关联的值是 raise 语句的第二个参数。 如果异常类是从标准根类 BaseException 派生的，则相关值作为异常实例的 args 属性存在。

用户代码可以引发内置异常。 这可用于测试异常处理程序或报告错误条件，“就像”解释器引发相同异常的情况一样； 但请注意，没有什么可以阻止用户代码引发不适当的错误。

内置的异常类可以被子类化以定义新的异常； 鼓励程序员从 Exception 类或其子类之一派生新异常，而不是从 BaseException。 有关定义异常的更多信息，请参阅 用户定义的异常 下的 Python 教程。

以下异常仅用作其他异常的基类。

exception exceptions.BaseException

所有内置异常的基类。 它并不意味着由用户定义的类直接继承（为此，请使用 Exception）。 如果在此类的实例上调用 str() 或 unicode()，则返回该实例的参数表示，或者返回空字符串没有争论。

2.5 版中的新功能。

args

提供给异常构造函数的参数元组。 一些内置异常（如 IOError）需要一定数量的参数并为此元组的元素分配特殊含义，而其他异常通常仅使用单个字符串调用并给出错误消息。

exception exceptions.Exception

所有内置的、非系统退出的异常都是从这个类派生的。 所有用户定义的异常也应该从这个类派生。

2.5 版更改： 更改为继承自 BaseException。

exception exceptions.StandardError

所有内置异常的基类，除了 StopIteration、GeneratorExit、KeyboardInterrupt 和 SystemExit。 StandardError 本身派生自 Exception。

exception exceptions.ArithmeticError

为各种算术错误引发的内置异常的基类：OverflowError、ZeroDivisionError、FloatingPointError。

exception exceptions.BufferError

当无法执行 缓冲区 相关操作时引发。

exception exceptions.LookupError

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

exception exceptions.EnvironmentError

Python 系统之外可能发生的异常的基类：IOError、OSError。 当使用 2 元组创建此类型的异常时，第一项在实例的 errno 属性上可用（假定为错误号），第二项在 strerror 属性（通常是相关的错误信息）。 元组本身也可在 args 属性上使用。

1.5.2 版中的新功能。

当 EnvironmentError 异常使用三元组实例化时，前两项如上可用，而第三项在 filename 属性上可用。 但是，为了向后兼容，args 属性仅包含前两个构造函数参数的 2 元组。

当使用 3 个参数以外的参数创建此异常时，filename 属性为 None。 errno 和 strerror 属性也是 None 当实例是用 2 或 3 个参数以外的参数创建的。 在最后一种情况下， args 包含逐字构造函数参数作为元组。

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

exception exceptions.AssertionError

当 assert 语句失败时引发。

exception exceptions.AttributeError

当属性引用（参见 属性引用 ）或赋值失败时引发。 （当对象根本不支持属性引用或属性分配时，会引发 TypeError。）

exception exceptions.EOFError

当其中一个内置函数（input() 或 raw_input()）在没有读取任何数据的情况下遇到文件结束条件 (EOF) 时引发。 （注意：file.read() 和 file.readline() 方法在遇到 EOF 时返回一个空字符串。）

exception exceptions.FloatingPointError

当浮点运算失败时引发。 这个异常总是被定义的，但只有在 Python 配置了 --with-fpectl 选项，或者 WANT_SIGFPE_HANDLER 符号在 pyconfig.h 文件中定义时才会引发。

exception exceptions.GeneratorExit

在调用 generator's close() 方法时引发。 它直接继承自 BaseException 而不是 StandardError，因为它在技术上不是错误。

2.5 版中的新功能。

2.6 版更改： 更改为继承自 BaseException。

exception exceptions.IOError

当 I/O 操作（例如 print 语句、内置的 open() 函数或文件对象的方法）对于 I/O 相关的操作失败时引发原因，例如“找不到文件”或“磁盘已满”。

此类派生自 EnvironmentError。 有关异常实例属性的更多信息，请参阅上面的讨论。

2.6 版更改： 更改 socket.error 以将其用作基类。

exception exceptions.ImportError

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

exception exceptions.IndexError

当序列下标超出范围时引发。 （切片索引被静默截断以落在允许的范围内；如果索引不是普通整数，则引发 TypeError。）

exception exceptions.KeyError

在现有键集中找不到映射（字典）键时引发。

exception exceptions.KeyboardInterrupt

当用户按下中断键时引发（通常是 Control-C 或 Delete）。 在执行期间，会定期检查中断。 当内置函数 input() 或 raw_input() 等待输入时输入的中断也会引发此异常。 该异常继承自 BaseException，以免被捕获 Exception 的代码意外捕获，从而阻止解释器退出。

2.5 版更改： 更改为继承自 BaseException。

exception exceptions.MemoryError

当操作耗尽内存时引发，但情况可能仍然可以挽救（通过删除一些对象）。 关联值是一个字符串，指示哪种（内部）操作耗尽了内存。 请注意，由于底层内存管理架构（C 的 malloc() 函数），解释器可能并不总是能够从这种情况中完全恢复； 尽管如此，它还是会引发异常，以便可以打印堆栈回溯，以防导致程序失控。

exception exceptions.NameError

在未找到本地或全局名称时引发。 这仅适用于非限定名称。 关联的值是一条错误消息，其中包含找不到的名称。

exception exceptions.NotImplementedError

此异常源自 RuntimeError。 在用户定义的基类中，抽象方法在需要派生类覆盖方法时应引发此异常。

1.5.2 版中的新功能。

exception exceptions.OSError

此异常源自 EnvironmentError。 当函数返回与系统相关的错误（不是针对非法参数类型或其他偶然错误）时引发。 errno 属性是来自 errno 的数字错误代码，strerror 属性是相应的字符串，如 C 函数 perror() 打印的那样. 请参阅模块 errno，其中包含由底层操作系统定义的错误代码的名称。

对于涉及文件系统路径的异常（例如 chdir() 或 unlink()），异常实例将包含第三个属性 filename，它是传递给功能。

1.5.2 版中的新功能。

exception exceptions.OverflowError

当算术运算的结果太大而无法表示时引发。 对于长整数（宁可引发 MemoryError 而不是放弃）和大多数使用纯整数的操作（返回长整数），这不会发生。 由于缺乏 C 中浮点异常处理的标准化，大多数浮点运算也没有被检查。

exception exceptions.ReferenceError

当由 weakref.proxy() 函数创建的弱引用代理用于访问被垃圾收集后的引用对象的属性时，会引发此异常。 有关弱引用的更多信息，请参阅 weakref 模块。

2.2 版新功能： 以前称为 weakref.ReferenceError 异常。

exception exceptions.RuntimeError

当检测到不属于任何其他类别的错误时引发。 相关联的值是一个字符串，指示出了什么问题。

exception exceptions.StopIteration

由 iterator's next() 方法引发，以表示没有其他值。 这是从 Exception 而不是 StandardError 派生的，因为这在其正常应用程序中不被视为错误。

2.2 版中的新功能。

exception exceptions.SyntaxError

当解析器遇到语法错误时引发。 这可能发生在 import 语句中，在 exec 语句中，在调用内置函数 eval() 或 input() 中，或者在读取初始脚本或标准输入时（也以交互方式）。

此类的实例具有属性 filename、lineno、offset 和 text，以便于访问详细信息。 异常实例的 str() 仅返回消息。

exception exceptions.IndentationError

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

exception exceptions.TabError

当缩进包含不一致的制表符和空格使用时引发。 这是 IndentationError 的子类。

exception exceptions.SystemError

当解释器发现内部错误时引发，但情况看起来并没有严重到使其放弃所有希望。 关联的值是一个字符串，指示出了什么问题（低级术语）。

您应该将此报告给 Python 解释器的作者或维护者。 请务必报告 Python 解释器的版本（sys.version；它也在交互式 Python 会话开始时打印）、确切的错误消息（异常的关联值）以及程序的源代码（如果可能）触发了错误。

exception exceptions.SystemExit

此异常由 sys.exit() 函数引发。 不处理时，Python解释器退出； 没有打印堆栈回溯。 如果关联值是普通整数，则指定系统退出状态（传递给 C 的 exit() 函数）； 如果是None，退出状态为零； 如果它有另一种类型（例如字符串），则打印对象的值并且退出状态为一个。

实例有一个属性 code，它被设置为建议的退出状态或错误消息（默认为 None）。 此外，此异常直接源自 BaseException 而不是 StandardError，因为它在技术上不是错误。

对 sys.exit() 的调用被转换为异常，以便可以执行清理处理程序（try 语句的 finally 子句），等等调试器可以在不冒失控风险的情况下执行脚本。 如果绝对有必要立即退出（例如，在调用 os.fork() 后的子进程中），则可以使用 os._exit() 函数。

异常继承自 BaseException 而不是 StandardError 或 Exception，因此它不会被捕获 Exception 的代码意外捕获。 这允许异常正确传播并导致解释器退出。

2.5 版更改： 更改为继承自 BaseException。

exception exceptions.TypeError

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

exception exceptions.UnboundLocalError

当在函数或方法中引用局部变量时引发，但没有值绑定到该变量。 这是 NameError 的子类。

2.0 版中的新功能。

exception exceptions.UnicodeError

当发生与 Unicode 相关的编码或解码错误时引发。 它是 ValueError 的子类。

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

encoding

引发错误的编码的名称。

reason

描述特定编解码器错误的字符串。

object

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

start

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

end

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

2.0 版中的新功能。

exception exceptions.UnicodeEncodeError

在编码期间发生与 Unicode 相关的错误时引发。 它是 UnicodeError 的子类。

2.3 版中的新功能。

exception exceptions.UnicodeDecodeError

在解码期间发生与 Unicode 相关的错误时引发。 它是 UnicodeError 的子类。

2.3 版中的新功能。

exception exceptions.UnicodeTranslateError

在翻译过程中发生与 Unicode 相关的错误时引发。 它是 UnicodeError 的子类。

2.3 版中的新功能。

exception exceptions.ValueError

当操作或函数收到具有正确类型但值不合适的参数时引发，并且这种情况没有用更精确的异常来描述，例如 IndexError。

exception exceptions.VMSError

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

exception exceptions.WindowsError

当发生特定于 Windows 的错误或错误编号与 errno 值不对应时引发。 winerror 和 strerror 值是从 Windows 平台 API 的 GetLastError() 和 FormatMessage() 函数的返回值创建的。 errno 值将 winerror 值映射到相应的 errno.h 值。 这是 OSError 的子类。

2.0 版中的新功能。

2.5 版本变化： 以前的版本将 GetLastError() 代码放入 errno。

exception exceptions.ZeroDivisionError

当除法或模运算的第二个参数为零时引发。 关联值是一个字符串，指示操作数和操作的类型。

以下异常用作警告类别； 有关更多信息，请参阅 warnings 模块。

exception exceptions.Warning

警告类别的基类。

exception exceptions.UserWarning

用户代码生成的警告的基类。

exception exceptions.DeprecationWarning

有关已弃用功能的警告的基类。

exception exceptions.PendingDeprecationWarning

有关将来不推荐使用的功能的警告的基类。

exception exceptions.SyntaxWarning

有关可疑语法的警告的基类。

exception exceptions.RuntimeWarning

有关可疑运行时行为的警告的基类。

exception exceptions.FutureWarning

有关将来会在语义上发生变化的构造的警告的基类。

exception exceptions.ImportWarning

关于模块导入中可能错误的警告的基类。

2.5 版中的新功能。

exception exceptions.UnicodeWarning

与 Unicode 相关的警告的基类。

2.5 版中的新功能。

exception exceptions.BytesWarning

与字节和字节数组相关的警告的基类。

2.6 版中的新功能。

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