# 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）的表示，或者当没有参数时返回空字符串。

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

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

exception `ImportError`

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

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

  在版本3.3中已更改：添加了`name`和`path`属性。

exception `IndexError`

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

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 `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` `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`。

  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 `BytesWarning`

  与`bytes`和`bytearray`相关的警告的基类。

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