5。内建异常

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

下面列出的异常可以通过解释器或内建函数生成。除了提到的那些地方,它们还有“关联值 (associated value)”指示错误的详细的原因。这可以是字符串或包含几个信息项(例如,错误码和解释错误码的字符串)的元组。这些关联值通常会作为参数,传递给异常类的构造函数。

用户代码可以引发内建异常。这样可以用于测试异常处理程序或报告错误条件,模拟解析器发生了相同的异常情况;但请注意,没有任何手段可以防止用户代码引起不适当的异常。

内建异常类可以被子类化以定义新异常;建议程序员从Exception类或其子类中的一个派生新异常,而不是从BaseException派生新异常。有关定义异常的详细信息可以查阅《Python 教程》中的 User-defined Exceptions 一节。

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

When raising a new exception (rather than using a bare raise to re-raise the exception currently being handled), the implicit exception context can be supplemented with an explicit cause by using from with raise:

raise new_exc from original_exc

The expression following from must be an exception or None. 它将在引发异常上设置为__cause__设置__ cause __还会将__ suppress_context __属性隐式设置为True,以便使用raise new_exc from None有效地替换旧的异常用于显示目的。KeyError转换为AttributeError,同时在调试时保留__context__中的旧异常可用于内省。

默认回溯显示代码显示这些链接异常以及异常本身的追溯。__cause__中的显式链接异常在出现时始终显示。仅当__cause__None__suppress_context__为假时,才会显示__context__中的隐式链接异常。

在任何情况下,异常本身始终显示在任何链接异常之后,以便追溯的最后一行总是显示最后引发的异常。

5.1.基类

The following exceptions are used mostly as base classes for other exceptions.

exception BaseException

所有内建的异常的基类。它并不意味用户定义的类应该直接继承它(因此,请使用 Exception)。如果对这个类的实例调用str(),则返回实例的参数(s)的表示,或者当没有参数时返回空字符串。

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

buffer 相关的操作无法执行时引发。

exception LookupError

当用于映射或序列的键或索引无效时引发的异常的基类:IndexError, KeyError可以直接通过 codecs.lookup() 引发。

5.2.具体的异常

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

exception AssertionError

assert 语句失败时引发。

exception AttributeError

当属性引用(参见 Attribute references)或赋值失败时引发。(当对象根本不支持属性引用或属性赋值时,将引发 TypeError。)

exception EOFError

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

exception FloatingPointError

当浮点数操作失败时引发。该异常总是被定义的,但仅能当 Python 用 --with-fpectl 选项配置时,或当 pyconfig.h 文件中定义了 WANT_SIGFPE_HANDLER 符号时引发。

exception GeneratorExit

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

exception ImportError

import语句未能找到模块定义或 ... import 无法找到要导入的名称。

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

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

exception IndexError

当序列下标超出取值范围时引发。(片索引被静默截断到允许的范围内;如果索引不是整数,则会引发TypeError。)

exception KeyError

当在现有键的集合中找不到映射的(字典)键时引发。

exception KeyboardInterrupt

当用户按下中断键(通常是 DeleteControl-C)时引发。执行期间,会定期检查中断。该异常继承自 BaseException ,因此不会被 Exception 的捕获代码意外捕获,以防止解释器退出。

exception MemoryError

当一个操作将内存耗尽,但情况仍可挽救时(通过删除某些对象)时引发。关联值是一个字符串,它指示哪种(内部)操作耗尽了内存。注意,由于底层内存管理架构(C的malloc()函数),解释器可能不总是能够从这种情况完全恢复;它仍然引入了一个异常,以便可以打印堆栈跟踪,以防万一程序失败的原因。

exception NameError

当找不到本地或全局名称时引发。这仅适用于不合格的名称。关联值是一条错误消息,其中包括找不到的名称。

exception NotImplementedError

此异常是从 RuntimeError 派生的。当用户定义基类需要派生类重写方法时,抽象方法会引发该异常。

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.error select.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

When a generator or coroutine function returns, a new StopIteration instance is raised, and the value returned by the function is used as the value parameter to the constructor of the exception.

如果存在 __未来__ 导入 generator_stop指令引发StopIteration,它将被转换为RuntimeError(保留StopIteration作为新异常的原因)。

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

在版本3.5中已更改:引入了RuntimeError变换。

exception StopAsyncIteration

必须通过asynchronous iterator对象的__anext__()方法提高以停止迭代。

版本3.5中的新功能。

exception SyntaxError

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

该类的实例具有更容易访问相关细节的 filenametextlinenooffset 属性。向内建函数 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

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

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

当除法或取模运算的第 2 个参数为 0 时引发。关联值是一个字符串,它指出操作数的类型和运算符。

保留以下例外以与先前版本兼容:从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

Changed in version 3.5: Python now retries system calls when a syscall is interrupted by a signal, except if the signal handler raises an exception (see PEP 475 for the rationale), instead of raising 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

可疑 Runtime 行为警告基类。

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