内置异常 — Python 文档

内置异常

在 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__ 中的隐式链式异常。

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

从内置异常继承

用户代码可以创建从异常类型继承的子类。 建议一次只对一种异常类型进行子类化，以避免基类处理 args 属性之间的任何可能冲突，以及由于可能的内存布局不兼容。

基类

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

exception BaseException

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

args

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

with_traceback(tb)

此方法将 tb 设置为异常的新回溯并返回异常对象。 在 PEP 3134 的异常链接功能可用之前，它更常用。 以下示例展示了如何在保留回溯的同时将 SomeException 的实例转换为 OtherException 的实例。 一旦提出，当前帧就会被推到 OtherException 的回溯上，就像原始 SomeException 的回溯一样，如果我们允许它传播给调用者。

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() 直接引发。

具体例外

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

exception AssertionError

当 assert 语句失败时引发。

exception AttributeError

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

name 和 obj 属性可以使用构造函数的仅关键字参数进行设置。 设置后，它们分别表示尝试访问的属性的名称和为该属性访问的对象。

3.10 版本变更： 增加了 name 和 obj 属性。

exception EOFError

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

exception FloatingPointError

当前未使用。

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

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

name 属性可以使用构造函数的仅关键字参数来设置。 设置后，它表示尝试访问的变量的名称。

3.10 版更改： 添加 name 属性。

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 属性现在是传递给函数的原始文件名，而不是编码到 文件系统编码和错误处理程序或从 文件系统编码和错误处理程序解码的名称[ X211X]。 此外，还添加了 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异常构造函数的参数。

如果生成器代码直接或间接引发 StopIteration，则会将其转换为 RuntimeError（保留 StopIteration 作为新异常的原因）。

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

3.5 版更改： 通过 from __future__ import generator_stop 引入了 RuntimeError 转换，参见 PEP 479。

在 3.7 版更改：默认为所有代码启用 PEP 479：生成器中引发的 StopIteration 错误转换为 [ X166X]运行时错误。

exception StopAsyncIteration

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

3.5 版中的新功能。

exception SyntaxError(message, details)

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

异常实例的 str() 仅返回错误消息。 详细信息是一个元组，其成员也可作为单独的属性使用。

filename

发生语法错误的文件名。

lineno

错误发生在文件中的哪个行号。 这是 1 索引：文件中第一行的 lineno 为 1。

offset

发生错误的行中的列。 这是 1 索引：该行中的第一个字符的 offset 为 1。

text

错误中涉及的源代码文本。

end_lineno

错误发生在文件中的哪个行号结束。 这是 1 索引：文件中第一行的 lineno 为 1。

end_offset

发生错误的结束行中的列结束。 这是 1 索引：该行中的第一个字符的 offset 为 1。

对于 f-string 字段中的错误，消息以“f-string:”为前缀，偏移量是根据替换表达式构造的文本中的偏移量。 例如，编译 f'Bad {ab} field' 会产生这个 args 属性：('f-string: ...', (, 1, 2, '(ab)n', 1, 5))。

3.10 版更改： 添加 end_lineno 和 end_offset 属性。

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 上可用。

操作系统异常

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

exception BlockingIOError

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

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

characters_written

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

exception ChildProcessError

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

exception ConnectionError

连接相关问题的基类。

子类是 BrokenPipeError、ConnectionAbortedError、ConnectionRefusedError 和 ConnectionResetError。

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()）时引发。 在大多数 POSIX 平台上，如果操作尝试打开或遍历非目录文件，就好像它是目录一样，它也可能会引发。 对应于 errno ENOTDIR。

exception PermissionError

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

exception ProcessLookupError

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

exception TimeoutError

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

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

另请参阅

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

警告

以下异常用作警告类别； 有关更多详细信息，请参阅 警告类别 文档。

exception Warning

警告类别的基类。

exception UserWarning

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

exception DeprecationWarning

当这些警告是针对其他 Python 开发人员时，有关已弃用功能的警告的基类。

被默认警告过滤器忽略，__main__ 模块除外 (PEP 565)。 启用 Python 开发模式 会显示此警告。

PEP 387 中描述了弃用政策。

exception PendingDeprecationWarning

有关已过时且预计将来会弃用但目前尚未弃用的功能的警告的基类。

此类很少用于发出有关可能即将发生的弃用的警告是不寻常的，并且 DeprecationWarning 是已激活弃用的首选。

被默认警告过滤器忽略。 启用 Python 开发模式 会显示此警告。

PEP 387 中描述了弃用政策。

exception SyntaxWarning

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

exception RuntimeWarning

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

exception FutureWarning

当这些警告面向用 Python 编写的应用程序的最终用户时，有关已弃用功能的警告的基类。

exception ImportWarning

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

被默认警告过滤器忽略。 启用 Python 开发模式 会显示此警告。

exception UnicodeWarning

与 Unicode 相关的警告的基类。

exception EncodingWarning

与编码相关的警告的基类。

有关详细信息，请参阅 选择加入编码警告 。

3.10 版中的新功能。

exception BytesWarning

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

exception ResourceWarning

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

被默认警告过滤器忽略。 启用 Python 开发模式 会显示此警告。

3.2 版中的新功能。

异常层次

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

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
           +-- EncodingWarning
           +-- ResourceWarning