Skip to main content

5. 内置异常

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

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

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

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

当在 exceptfinally 子句中引发(或重新引发)异常时,__context__ 会自动设置为捕获的最后一个异常;如果未处理新的异常,则最终显示的追溯将包括原始异常和最终异常。

当提出一个新的异常(而不是使用裸 raise 重新提出当前正在处理的异常),隐式异常上下文可以通过使用 fromraise 显式原因补充:

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

对于各种算术错误引发的内置异常的基类:OverflowErrorZeroDivisionErrorFloatingPointError

exception BufferError

在无法执行 缓冲 相关操作时触发。

exception LookupError

在映射或序列上使用的键或索引无效时引发的异常的基类:IndexErrorKeyError。这可以由 codecs.lookup() 直接提出。

5.2. 具体异常

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

exception AssertionError

assert 语句失败时引发。

exception AttributeError

在属性引用(请参阅 属性引用)或赋值失败时引发。 (当对象不支持属性引用或属性分配时,将引发 TypeError。)

exception EOFError

input() 函数未读取任何数据时触发文件结束条件(EOF)时引发。 (N.B:当 io.IOBase.read()io.IOBase.readline() 方法命中EOF时,它们返回一个空字符串。)

exception FloatingPointError

在浮点操作失败时触发。此异常总是定义的,但只能在使用 --with-fpectl 选项配置Python或在 pyconfig.h 文件中定义 WANT_SIGFPE_HANDLER 符号时引发。

exception GeneratorExit

generatorcoroutine 关闭时引发;见 generator.close()coroutine.close()。它直接继承自 BaseException 而不是 Exception,因为它在技术上不是错误。

exception ImportError

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

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

在 3.3 版更改: 添加了 namepath 属性。

exception ModuleNotFoundError

当模块不能被定位时,由 import 产生的 ImportError 的子类。当在 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 exceptions 所述。特定的子类取决于最终的 errno 值。此行为仅在直接构造 OSError 或通过别名构造 OSError 时发生,并且在子类化时不会继承。

errno

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

winerror

在Windows下,这将提供本机Windows错误代码。 errno 属性然后是POSIX术语中的本机错误代码的近似翻译。

在Windows下,如果 winerror 构造函数参数是整数,则从Windows错误代码确定 errno 属性,并且忽略 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__next__() 方法引发,表示没有其他项目由迭代器产生。

异常对象具有单个属性 value,其在构造异常时作为参数给出,并且默认为 None

generatorcoroutine 函数返回时,将引发一个新的 StopIteration 实例,并将该函数返回的值用作异常构造函数的 value 参数。

如果在存在 from __future__ import generator_stop 指令的情况下定义的生成函数提高 StopIteration,则它将被转换为 RuntimeError (保留 StopIteration 作为新异常的原因)。

在 3.3 版更改: 添加了 value 属性和生成器函数使用它返回值的能力。

在 3.5 版更改: 引入了RuntimeError转换。

exception StopAsyncIteration

必须由 asynchronous iterator 对象的 __anext__() 方法引发以停止迭代。

3.5 新版功能.

exception SyntaxError

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

此类的实例具有属性 filenamelinenooffsettext,以便于访问详细信息。异常实例的 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,退出状态为零;如果它有另一个类型(例如字符串),则打印对象的值,退出状态为1。

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

在操作会阻塞设置为非阻塞操作的对象(例如套接字)时触发。对应于 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())时引发。对应于 errno ENOTDIR

exception PermissionError

在尝试运行没有足够访问权限的操作(例如文件系统权限)时引发。对应于 errno EACCESEPERM

exception ProcessLookupError

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

exception TimeoutError

在系统级别的系统函数超时时触发。对应于 errno ETIMEDOUT

3.3 新版功能: 添加所有上述 OSError 亚类。

参见

PEP 3151 - 重新修改操作系统和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

bytesbytearray 相关的警告的基类。

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