5. 内置异常

在 Python 中，所有异常都必须是派生自 BaseException 的类的实例。在带有 except 子句的 try 语句中，该子句提到了一个特定的类，该子句还处理从该类派生的任何异常类（但不处理 it ] 是派生的）。两个通过子类化不相关的异常类永远不会等价，即使它们具有相同的名称。

下面列出的内置异常可以由解释器或内置函数生成。除非另有说明，否则它们都有一个“关联值”，指示错误的详细原因。这可能是一个字符串或多个信息项的元组（例如，错误代码和解释代码的字符串）。关联的值通常作为参数传递给异常类的构造函数。

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

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

当在 except 或 finally 子句中引发（或重新引发）异常时，__context__ 会自动设置为最后捕获的异常；如果未处理新异常，则最终显示的回溯将包括原始异常和最终异常。

当引发一个新的异常时（而不是使用一个空的 raise 来重新引发当前正在处理的异常），隐式异常上下文可以通过使用 from 和来补充一个显式原因X219X]加注：

raise new_exc from original_exc

from 后面的表达式必须是异常或 None。在引发的异常中，它将被设置为 __cause__。设置 __cause__ 还隐式地将 __suppress_context__ 属性设置为 True，以便使用 raise new_exc from None 有效地用新异常替换旧异常以用于显示目的（例如将 KeyError 转换为 AttributeError)，同时保留 __context__ 中可用的旧异常，以便在调试时进行自省。

除了异常本身的回溯之外，默认回溯显示代码还显示这些链式异常。 __cause__ 中的显式链接异常始终在出现时显示。仅当 __cause__ 为 None 且 __suppress_context__ 为假时，才会显示 __context__ 中的隐式链式异常。

在任何一种情况下，异常本身总是显示在任何链式异常之后，以便回溯的最后一行总是显示最后一个引发的异常。

5.1. 基类

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

exception BaseException

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

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

with_traceback(tb)

此方法将 tb 设置为异常的新回溯并返回异常对象。它通常用于像这样的异常处理代码：

try:
    ...
except SomeException:
    tb = sys.exc_info()[2]
    raise OtherException(...).with_traceback(tb)

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

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

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

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

5.2. 具体例外

以下异常是通常引发的异常。

exception AssertionError: 当 assert 语句失败时引发。

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

exception EOFError: 当 input() 函数在没有读取任何数据的情况下达到文件结束条件 (EOF) 时引发。（注意：io.IOBase.read() 和 io.IOBase.readline() 方法在遇到 EOF 时返回一个空字符串。）

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

exception GeneratorExit: 当 generator 或 coroutine 关闭时引发；参见 generator.close() 和 coroutine.close()。它直接继承自 BaseException 而不是 Exception，因为它在技术上不是错误。

exception ImportError

当 import 语句在尝试加载模块时遇到问题时引发。当 from ... import 中的“来自列表”的名称无法找到时也会引发。

name 和 path 属性可以使用构造函数的仅关键字参数进行设置。设置后，它们分别表示尝试导入的模块的名称和触发异常的任何文件的路径。

3.3 版本变更：增加了 name 和 path 属性。

exception ModuleNotFoundError: ImportError 的子类，当找不到模块时由 import 引发。当在 sys.modules 中找到 None 时，它也会引发。

3.6 版中的新功能。

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

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

exception KeyboardInterrupt: 当用户按下中断键时引发（通常是 Control-C 或 Delete）。在执行期间，会定期检查中断。该异常继承自 BaseException，以免被捕获 Exception 的代码意外捕获，从而阻止解释器退出。

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

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

exception NotImplementedError: 此异常源自 RuntimeError。在用户定义的基类中，抽象方法在需要派生类覆盖方法时，或者在开发类以指示仍然需要添加真正的实现时，应该引发此异常。

笔记

它不应该用于表示根本不支持运算符或方法——在这种情况下，要么不定义运算符/方法，要么如果是子类，则将其设置为 None。

笔记

NotImplementedError 和 NotImplemented 不可互换，即使它们具有相似的名称和用途。有关何时使用它的详细信息，请参阅 NotImplemented。

exception OSError([arg]) exception OSError(errno, strerror[, filename[, winerror[, filename2]]])

当系统函数返回与系统相关的错误时会引发此异常，包括 I/O 故障，例如“找不到文件”或“磁盘已满”（不适用于非法参数类型或其他偶然错误）。

构造函数的第二种形式设置了相应的属性，如下所述。如果未指定，则属性默认为 None。为了向后兼容，如果传递了三个参数，args 属性只包含前两个构造函数参数的 2 元组。

构造函数通常实际上返回 OSError 的子类，如下面的 OS 异常中所述。特定的子类取决于最终的 errno 值。此行为仅在直接或通过别名构造 OSError 时发生，并且在子类化时不会继承。

errno: 来自 C 变量 errno 的数字错误代码。

winerror

在 Windows 下，这会为您提供本地 Windows 错误代码。 errno 属性则是该本地错误代码的近似翻译，在 POSIX 术语中。

在 Windows 下，如果 winerror 构造函数参数为整数，则 errno 属性由 Windows 错误代码确定，而忽略 errno 参数。在其他平台上，winerror 参数被忽略，winerror 属性不存在。

strerror: 相应的错误消息，由操作系统提供。它由POSIX下的C函数perror()和Windows下的FormatMessage()格式化。

filename filename2: 对于涉及文件系统路径的异常（例如 open() 或 os.unlink()），filename 是传递给函数的文件名。对于涉及两个文件系统路径的函数（如os.rename()），filename2对应传递给函数的第二个文件名。

3.3 版本更改： EnvironmentError、IOError、WindowsError、socket.error、select。 error 和 mmap.error 已经合并到 OSError 中，构造函数可能会返回一个子类。

3.4 版更改： filename 属性现在是传递给函数的原始文件名，而不是编码为文件系统编码或从文件系统编码解码的名称。此外，还添加了 filename2 构造函数参数和属性。

exception OverflowError: 当算术运算的结果太大而无法表示时引发。这不会发生在整数（宁可引发 MemoryError 而不是放弃）。但是，由于历史原因，有时会为超出所需范围的整数引发 OverflowError。由于 C 中缺乏对浮点异常处理的标准化，大多数浮点运算没有被检查。

exception RecursionError: 此异常源自 RuntimeError。当解释器检测到超过最大递归深度（参见 sys.getrecursionlimit()）时，它会被引发。

3.5 版新功能：以前，一个普通的 RuntimeError 被提出。

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

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

exception StopIteration

由内置函数 next() 和 iterator's __next__() 方法引发，以表示迭代器不再产生其他项目.

异常对象有一个属性 value，在构造异常时作为参数给出，默认为 None。

当 generator 或 coroutine 函数返回时，会引发一个新的 StopIteration 实例，并将该函数返回的值用作 value异常构造函数的参数。

如果在存在 from __future__ import generator_stop 指令的情况下定义的生成器函数引发 StopIteration，它将被转换为 RuntimeError（保留 StopIteration 作为新异常的原因）。

3.3 版更改：添加 value 属性以及生成器函数使用它返回值的能力。

3.5 版更改：引入了 RuntimeError 转换。

exception StopAsyncIteration: 必须由异步迭代器对象的 __anext__() 方法引发以停止迭代。

3.5 版中的新功能。

exception SyntaxError

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

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

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

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

exception SystemError

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

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

exception SystemExit

此异常由 sys.exit() 函数引发。它继承自 BaseException 而不是 Exception，因此它不会被捕获 Exception 的代码意外捕获。这允许异常正确传播并导致解释器退出。不处理时，Python解释器退出；没有打印堆栈回溯。构造函数接受传递给 sys.exit() 的相同可选参数。如果值为整数，则指定系统退出状态（传递给C的exit()函数）；如果是None，退出状态为零；如果它有另一种类型（例如字符串），则打印对象的值并且退出状态为一个。

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

code: 传递给构造函数的退出状态或错误消息。（默认为 None。）

exception TypeError

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

用户代码可能会引发此异常，以指示不支持并且不打算支持对对象进行的尝试操作。如果对象旨在支持给定的操作但尚未提供实现，则 NotImplementedError 是引发的正确异常。

传递错误类型的参数（例如当期望 int 时传递 list）应该导致 TypeError，但传递带有错误值的参数（例如超出预期边界的数字）应导致 ValueError。

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

exception UnicodeError

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

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

encoding: 引发错误的编码的名称。

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

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

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

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

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

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

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

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

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

保留以下例外情况是为了与以前的版本兼容；从 Python 3.3 开始，它们是 OSError 的别名。

exception EnvironmentError

exception IOError

exception WindowsError: 仅在 Windows 上可用。

5.2.1. 操作系统异常

以下异常是 OSError 的子类，它们根据系统错误代码引发。

exception BlockingIOError

当操作阻塞对象时引发（例如 socket) 设置为非阻塞操作。对应于 errno EAGAIN、EALREADY、EWOULDBLOCK 和 EINPROGRESS。

除了 OSError 的那些，BlockingIOError 还可以有一个属性：

characters_written: 一个整数，包含在阻塞之前写入流的字符数。当使用来自 io 模块的缓冲 I/O 类时，此属性可用。

exception ChildProcessError: 当对子进程的操作失败时引发。对应于 errno ECHILD。

exception ConnectionError

exception BrokenPipeError: ConnectionError 的子类，在另一端关闭时尝试在管道上写入时引发，或尝试在已关闭以进行写入的套接字上写入时引发。对应于 errno EPIPE 和 ESHUTDOWN。

exception ConnectionAbortedError: ConnectionError 的子类，在对等方中止连接尝试时引发。对应于 errno ECONNABORTED。

exception ConnectionRefusedError: ConnectionError 的子类，在对等方拒绝连接尝试时引发。对应于 errno ECONNREFUSED。

exception ConnectionResetError: ConnectionError 的子类，在对等方重置连接时引发。对应于 errno ECONNRESET。

exception FileExistsError: 在尝试创建已存在的文件或目录时引发。对应于 errno EEXIST。

exception FileNotFoundError: 当请求文件或目录但不存在时引发。对应于 errno ENOENT。

exception InterruptedError: 当系统调用被传入信号中断时引发。对应于 errno EINTR。

3.5 版更改：Python 现在在系统调用被信号中断时重试系统调用，除非信号处理程序引发异常（请参阅 PEP 475基本原理），而不是引发 InterruptedError。

exception IsADirectoryError: 在目录上请求文件操作（例如 os.remove()）时引发。对应于 errno EISDIR。

exception NotADirectoryError: 当对非目录的内容请求目录操作（例如 os.listdir()）时引发。对应于 errno ENOTDIR。

exception PermissionError: 在没有足够访问权限的情况下尝试运行操作时引发 - 例如文件系统权限。对应于 errno EACCES 和 EPERM。

exception ProcessLookupError: 当给定进程不存在时引发。对应于 errno ESRCH。

exception TimeoutError: 当系统功能在系统级别超时时引发。对应于 errno ETIMEDOUT。

3.3 新功能：增加了以上所有的 OSError 子类。

也可以看看

PEP 3151 - 重新设计 OS 和 IO 异常层次结构

5.3. 警告

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

exception Warning: 警告类别的基类。

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

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

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

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

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

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

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

exception UnicodeWarning: 与 Unicode 相关的警告的基类。

exception BytesWarning: 与 bytes 和 bytearray 相关警告的基类。

exception ResourceWarning: 与资源使用相关的警告的基类。

3.2 版中的新功能。

5.4. 异常层次

内置异常的类层次结构是：

BaseException
 +-- SystemExit
 +-- KeyboardInterrupt
 +-- GeneratorExit
 +-- Exception
      +-- StopIteration
      +-- StopAsyncIteration
      +-- ArithmeticError
      |    +-- FloatingPointError
      |    +-- OverflowError
      |    +-- ZeroDivisionError
      +-- AssertionError
      +-- AttributeError
      +-- BufferError
      +-- EOFError
      +-- ImportError
      |    +-- ModuleNotFoundError
      +-- LookupError
      |    +-- IndexError
      |    +-- KeyError
      +-- MemoryError
      +-- NameError
      |    +-- UnboundLocalError
      +-- OSError
      |    +-- BlockingIOError
      |    +-- ChildProcessError
      |    +-- ConnectionError
      |    |    +-- BrokenPipeError
      |    |    +-- ConnectionAbortedError
      |    |    +-- ConnectionRefusedError
      |    |    +-- ConnectionResetError
      |    +-- FileExistsError
      |    +-- FileNotFoundError
      |    +-- InterruptedError
      |    +-- IsADirectoryError
      |    +-- NotADirectoryError
      |    +-- PermissionError
      |    +-- ProcessLookupError
      |    +-- TimeoutError
      +-- ReferenceError
      +-- RuntimeError
      |    +-- NotImplementedError
      |    +-- RecursionError
      +-- SyntaxError
      |    +-- IndentationError
      |         +-- TabError
      +-- SystemError
      +-- TypeError
      +-- ValueError
      |    +-- UnicodeError
      |         +-- UnicodeDecodeError
      |         +-- UnicodeEncodeError
      |         +-- UnicodeTranslateError
      +-- Warning
           +-- DeprecationWarning
           +-- PendingDeprecationWarning
           +-- RuntimeWarning
           +-- SyntaxWarning
           +-- UserWarning
           +-- FutureWarning
           +-- ImportWarning
           +-- UnicodeWarning
           +-- BytesWarning
           +-- ResourceWarning

5. 内置异常 — Python 文档