内置异常 — 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 设置为异常的新回溯并返回异常对象。 它通常用于像这样的异常处理代码:
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 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
- 在未找到本地或全局名称时引发。 这仅适用于非限定名称。 关联的值是一条错误消息,其中包含找不到的名称。
- 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
异常构造函数的参数。如果生成器代码直接或间接引发 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
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 子类。
警告
以下异常用作警告类别; 有关更多详细信息,请参阅 警告类别 文档。
- 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 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