5。内建异常¶
在 Python 中,所有的异常必须是从 BaseException
中派生的类的实例.在带有提及特定类的except
子句的try
语句中,该子句还处理从该类派生的任何异常类(但不包括)。通过子类化得到的两个不相关的异常类永远不会相等,即便它们具有相同的名称。
下列内建异常可以通过解释器或者内建函数来生成。除了提到的那些地方,它们还有“关联值 (associated value)”指示错误的详细的原因。这可以是字符串或包含几个信息项(例如,错误码和解释错误码的字符串)的元组。这些关联值通常会作为参数,传递给异常类的构造函数。
用户代码可产生内建异常。这样可以用于测试异常处理程序或报告错误条件,模拟解析器发生了相同的异常情况;但请注意,没有任何手段可以防止用户代码引起不适当的异常。
内建异常类可以被子类化以定义新异常;建议程序员从Exception
类或其子类中的一个派生新异常,而不是从BaseException
派生新异常。有关定义异常的详细信息可以查阅《Python 教程》中的 User-defined Exceptions 一节。
在except
或finally
子句__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)的表示,或者当没有参数时返回空字符串。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
LookupError
¶ 当用于映射或序列的键或索引无效时引发的异常的基类:
IndexError
,KeyError
。可以直接通过codecs.lookup()
引发。
5.2.具体的异常¶
以下异常是通常引发的异常。
- 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
¶ 在generator或coroutine关闭时触发;参见
generator.close()
和coroutine.close()
。它直接继承自BaseException
而不是Exception
,因为它在技术上不是错误。
- exception
ImportError
¶ 在
import
语句未能找到模块定义或从 ... import
无法找到要导入的名称。可以使用构造函数的仅关键字参数来设置
name
和path
属性。设置时,它们分别表示尝试导入的模块的名称和触发异常的任何文件的路径。在版本3.3中已更改:添加了
name
和path
属性。
- exception
KeyError
¶ 当在现有键的集合中找不到映射的(字典)键时引发。
- exception
KeyboardInterrupt
¶ 当用户按下中断键(通常是
Delete
或Control-C
)时引发。执行期间,会定期检查中断。该异常继承自BaseException
,因此不会被Exception
的捕获代码意外捕获,以防止解释器退出。
- exception
MemoryError
¶ 当一个操作将内存耗尽,但情况仍可挽救时(通过删除某些对象)时引发。关联值是一个字符串,它指示哪种(内部)操作耗尽了内存。注意,由于底层内存管理架构(C的
malloc()
函数),解释器可能不总是能够从这种情况完全恢复;它仍然引入了一个异常,以便可以打印堆栈跟踪,以防万一程序失败的原因。
- exception
NameError
¶ 当找不到本地或全局名称时引发。这仅适用于不合格的名称。关联值是一条错误消息,其中包括找不到的名称。
- exception
NotImplementedError
¶ 此异常是从
RuntimeError
派生的。当用户定义基类需要派生类重写方法时,抽象方法会引发该异常。
- exception
OSError
([arg])¶ - exception
OSError
(errno, strerror[, filename[, winerror[, filename2]]]) This exception is raised when a system function returns a system-related error, including I/O failures such as “file not found” or “disk full” (not for illegal argument types or other incidental errors).
第二种形式的构造函数设置相应的属性,如下所述。如果未指定,属性默认为
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的__next__()
方法引发, 。异常对象具有单个属性
value
,作为构造异常时的参数,默认为None
。当generator或coroutine函数返回时,将引发一个新的
StopIteration
实例,并将该函数返回的值用作value
参数指向异常的构造函数。如果存在
从 __未来__ 导入 generator_stop
指令引发StopIteration
,它将被转换为RuntimeError
(保留StopIteration
作为新异常的原因)。在版本3.3中已更改:添加了
value
属性和生成器函数用于返回值的能力。在版本3.5中已更改:引入了RuntimeError变换。
- exception
StopAsyncIteration
¶ 必须通过asynchronous iterator对象的
__anext__()
方法提高以停止迭代。版本3.5中的新功能。
- exception
SyntaxError
¶ 当解析器遇到语法错误时引发。这可能发生在
import
语句中,在调用内建函数exec()
或eval()
脚本或标准输入(也是交互式)。该类的实例具有更容易访问相关细节的
filename
、text
、lineno
、offset
属性。向内建函数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
UnicodeError
¶ 当有关 Unicode 编码或解码错误出现时引发。它是
ValueError
的一个子类。UnicodeError
具有描述编码或解码错误的属性。例如,err.object[err.start:err.end]
给出了导致解码器失败的特定的无效输入。encoding
¶引发错误的编码名称。
reason
¶一个字符串,它描述特定的解码器错误。
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
EAGAIN
,EALREADY
,EWOULDBLOCK
和EINPROGRESS
。除了
OSError
之外,BlockingIOError
还可以有一个属性:
- 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
。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
EACCES
和EPERM
。
- 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
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