内置异常 — Python 文档

来自菜鸟教程
Python/docs/3.9/library/exceptions
跳转至:导航、​搜索

内置异常

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

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

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

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

异常上下文

当在 exceptfinally 子句中引发(或重新引发)异常时,__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 设置为异常的新回溯并返回异常对象。 它通常用于像这样的异常处理代码:

try:
    ...
except SomeException:
    tb = sys.exc_info()[2]
    raise OtherException(...).with_traceback(tb)
exception Exception
所有内置的、非系统退出的异常都是从这个类派生的。 所有用户定义的异常也应该从这个类派生。
exception ArithmeticError
为各种算术错误引发的内置异常的基类:OverflowErrorZeroDivisionErrorFloatingPointError
exception BufferError
当无法执行 缓冲区 相关操作时引发。
exception LookupError
当映射或序列上使用的键或索引无效时引发的异常的基类:IndexErrorKeyError。 这可以通过 codecs.lookup() 直接引发。


具体例外

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

exception AssertionError
assert 语句失败时引发。
exception AttributeError
当属性引用(参见 属性引用 )或赋值失败时引发。 (当对象根本不支持属性引用或属性分配时,会引发 TypeError。)
exception EOFError
input() 函数在没有读取任何数据的情况下达到文件结束条件 (EOF) 时引发。 (注意:io.IOBase.read()io.IOBase.readline() 方法在遇到 EOF 时返回一个空字符串。)
exception FloatingPointError
当前未使用。
exception GeneratorExit
generatorcoroutine 关闭时引发; 参见 generator.close()coroutine.close()。 它直接继承自 BaseException 而不是 Exception,因为它在技术上不是错误。
exception ImportError

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

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

3.3 版本变更: 增加了 namepath 属性。

exception ModuleNotFoundError

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

3.6 版中的新功能。

exception IndexError
当序列下标超出范围时引发。 (切片索引被静默截断以落在允许的范围内;如果索引不是整数,则会引发 TypeError。)
exception KeyError
在现有键集中找不到映射(字典)键时引发。
exception KeyboardInterrupt
当用户按下中断键时引发(通常是 Control-CDelete)。 在执行期间,会定期检查中断。 该异常继承自 BaseException,以免被捕获 Exception 的代码意外捕获,从而阻止解释器退出。
exception MemoryError
当操作耗尽内存时引发,但情况可能仍然可以挽救(通过删除一些对象)。 关联值是一个字符串,指示哪种(内部)操作耗尽了内存。 请注意,由于底层内存管理架构(C 的 malloc() 函数),解释器可能并不总是能够从这种情况中完全恢复; 尽管如此,它还是会引发异常,以便可以打印堆栈回溯,以防导致程序失控。
exception NameError
在未找到本地或全局名称时引发。 这仅适用于非限定名称。 关联的值是一条错误消息,其中包含找不到的名称。
exception NotImplementedError

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

笔记

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

笔记

NotImplementedErrorNotImplemented 不可互换,即使它们具有相似的名称和用途。 有关何时使用它的详细信息,请参阅 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 版本更改: EnvironmentErrorIOErrorWindowsErrorsocket.errorselect。 errormmap.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

generatorcoroutine 函数返回时,会引发一个新的 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

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

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

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 EAGAINEALREADYEWOULDBLOCKEINPROGRESS

除了 OSError 的那些,BlockingIOError 还可以有一个属性:

characters_written

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

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

连接相关问题的基类。

子类是 BrokenPipeErrorConnectionAbortedErrorConnectionRefusedErrorConnectionResetError

exception BrokenPipeError
ConnectionError 的子类,在另一端关闭时尝试在管道上写入时引发,或尝试在已关闭以进行写入的套接字上写入时引发。 对应于 errno EPIPEESHUTDOWN
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 EACCESEPERM
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 BytesWarning
bytesbytearray 相关警告的基类。
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
           +-- ResourceWarning