Docs4dev
Docs
python / 3.7.2rc1 / all / library-exceptions.html

Built-in Exceptions

在 Python 中，所有异常都必须是从BaseException派生的类的实例。在带有except子句的try语句中，该子句提到特定的类，该子句还处理从该类派生的任何异常类(但不处理派生* it *的异常类)。pass子类不相关的两个异常类即使名称相同，也永远不会等效。

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

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

内置的异常类可以被子类化以定义新的异常。鼓励程序员从Exception类或其子类之一而不是BaseException派生新的异常。有关定义异常的更多信息，请参见 Python 教程中的User-defined Exceptions。

引发(或重新引发)except或finally子句__context__中的异常时，会自动将其设置为最后捕获的异常；如果未处理新的异常，则finally显示的回溯将包括原始异常和finally异常。

引发新异常时(而不是使用裸露的raise重新引发当前正在处理的异常)，可以pass将from与raise结合使用隐式异常上下文来补充显式原因：

raise new_exc from original_exc

from之后的表达式必须是None或 exception。引发异常时，它将设置为__cause__。设置__cause__也会将__suppress_context__属性隐式设置为True，以便使用raise new_exc from None有效地将旧异常替换为新异常以用于显示(例如，将KeyError转换为AttributeError)，同时在调试时将旧异常保留在__context__中以进行自省。

默认的回溯显示代码除了显示异常本身的回溯之外，还显示这些链接的异常。如果存在，总是显示__cause__中的显式链接异常。仅当__cause__为None并且__suppress_context__为 false 时，才会显示__context__中的隐式链接异常。

在这两种情况下，总是在任何链接的异常之后显示异常本身，以使回溯的最后一行始终显示最后引发的异常。

Base classes

以下异常通常用作其他异常的 Base Class。

  • exception BaseException

    • 所有内置异常的 Base Class。它并不意味着要由用户定义的类直接继承(为此，请使用Exception)。如果在此类的实例上调用str()，则返回该实例的参数表示形式；如果没有参数，则返回空字符串。

  • args

    • 给异常构造函数的参数的 Tuples。一些内置的异常(例如OSError)期望有一定数量的参数，并为此 Tuples 的元素分配特殊的含义，而其他一些异常通常仅使用给出错误消息的单个字符串来调用。

  • with_traceback(* tb *)

    • 此方法将* tb *设置为该异常的新回溯并返回异常对象。它通常用于如下的异常处理代码中：
try:
    ...
except SomeException:
    tb = sys.exc_info()[2]
    raise OtherException(...).with_traceback(tb)

  • exception Exception

    • 所有内置的，非系统退出的异常都从此类派生。所有用户定义的异常也应从此类派生。

  • exception ArithmeticError

  • exception BufferError

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

  • exception LookupError

Concrete exceptions

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

  • exception AssertionError
    • assert语句失败时引发。

  • exception AttributeError

    • 在属性引用(请参见Attribute references)或分配失败时引发。 (当一个对象根本不支持属性引用或属性分配时，将引发TypeError。)

  • exception EOFError

    • 在input()函数达到文件结束条件(EOF)而不读取任何数据时引发。 (注：io.IOBase.read()和io.IOBase.readline()方法在到达 EOF 时返回空字符串。)

  • exception FloatingPointError

    • 目前未使用。

  • exception GeneratorExit

  • exception ImportError

    • 在import语句try加载模块时遇到问题时引发。当from ... import中的“来自列表”具有无法找到的名称时也会引发。

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

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

  • exception ModuleNotFoundError

3.6 版的新Function。

  • exception IndexError

    • 当序列下标超出范围时引发。 (切片索引会被静默地截断以使其落在允许的范围内；如果索引不是整数，则引发TypeError。)

  • exception KeyError

    • 当在现有键集中找不到 Map(字典)键时引发。

  • exception KeyboardInterrupt

    • 当用户按下break键(通常为 Control-C 或 Delete)时触发。在执行期间，会定期检查break。异常继承自BaseException，以免被捕获Exception的代码意外捕获，从而防止解释器退出。

  • exception MemoryError

    • 在操作内存不足时引发，但这种情况仍然可以挽救(pass删除某些对象)。关联值是一个字符串，指示哪种(内部)操作用完了内存。注意，由于底层的内存 Management 体系结构(C 的malloc()函数)，解释器可能无法始终完全从这种情况恢复；尽管如此，它还是引发了一个 exception，以便在导致程序失控的情况下可以打印堆栈回溯。

  • exception NameError

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

  • exception NotImplementedError

    • 此异常源自RuntimeError。在用户定义的 Base Class 中，当抽象方法要求派生类重写该方法时，或者在开发该类以指示仍需要添加实际实现时，应引发此异常。

Note

它不应用于表示完全不支持运算符或方法，在这种情况下，请不要定义运算符/方法，或者如果是子类，请将其设置为None。

Note

NotImplementedError和NotImplemented即使名称和用途相似，也不能互换。有关何时使用的详细信息，请参见NotImplemented。

    • exception * OSError([* arg *])
    • exception * OSError(* errno ， strerror * [，* filename * [，* winerror * [，* filename2 *]]])
    • 当系统函数返回与系统相关的错误(包括“找不到文件”或“磁盘已满”之类的 I/O 故障(不适用于非法参数类型或其他偶然错误))时，引发此异常。

构造函数的第二种形式设置相应的属性，如下所述。如果未指定，则属性默认为None。为了向后兼容，如果传递了三个参数，则args属性仅包含前两个构造函数参数中的 2Tuples。

构造函数通常实际上返回OSError的子类，如下面OS exceptions所述。特定的子类取决于finally的errno值。此行为仅在直接或pass别名构造OSError时发生，并且在子类化时不会继承。

  • errno

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

  • winerror

    • 在 Windows 下，这将为您提供本机 Windows 错误代码。 errno属性是该本地错误代码的近似翻译，以 POSIX 术语表示。

在 Windows 下，如果* winerror 构造函数参数是整数，则errno属性由 Windows 错误代码确定，而 errno 参数将被忽略。在其他平台上， winerror *参数将被忽略，并且winerror属性不存在。

  • strerror

    • 相应的错误消息，由 os 提供。它由 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

版本 3.5 中的新Function：以前，提出了一个普通的RuntimeError。

  • exception ReferenceError

    • 当由weakref.proxy()函数创建的弱引用代理服务器被垃圾回收后，用于访问引用对象的属性时，会引发此异常。有关弱引用的更多信息，请参见weakref模块。

  • exception RuntimeError

    • 在检测到不属于任何其他类别的错误时引发。关联的值是一个字符串，指示确切地出错了。

  • exception StopIteration

    • 由内置函数next()和iterator的next()方法引发，以表示迭代器不再产生其他项。

异常对象具有单个属性value，该属性在构造异常时作为参数提供，默认为None。

当generator或coroutine函数返回时，将引发一个新的StopIteration实例，并且该函数返回的值用作该异常的构造函数的value参数。

如果生成器代码直接或间接引发StopIteration，则它将转换为RuntimeError(保留StopIteration作为新的异常原因)。

在版本 3.3 中进行了更改：添加了value属性，并且生成器函数可以使用它返回值。

在版本 3.5 中进行了更改：passfrom __future__ import generator_stop引入了 RuntimeError 转换，请参见 PEP 479。

在版本 3.7 中更改：默认情况下为所有代码启用 PEP 479：生成器中引发的StopIteration错误转换为RuntimeError。

3.5 版中的新Function。

  • exception SyntaxError
    • 在解析器遇到语法错误时引发。这可能发生在import语句中，对内置函数exec()或eval()的调用中，或者在读取初始脚本或标准 Importing 时(也以交互方式)。

此类的实例具有属性filename，lineno，offset和text，以便更轻松地访问详细信息。异常实例的str()仅返回消息。

  • exception IndentationError

    • 与缩进不正确相关的语法错误的 Base Class。这是SyntaxError的子类。

  • exception TabError

    • 当缩进包含制表符和空格的不一致使用时引发。这是IndentationError的子类。

  • exception SystemError

    • 在解释器发现内部错误时引发，但情况看起来并不那么严重，以致它放弃了所有希望。关联的值是一个字符串，用于指示出了什么问题(以低级术语表示)。

您应该将此报告给 Python 解释器的作者或维护者。请确保报告 Python 解释器的版本(sys.version；它也将在交互式 Python 会话的开始时打印)，确切的错误消息(与异常相关的值)以及可能的触发错误的程序源。

  • exception SystemExit
    • sys.exit()函数引发了此异常。它继承自BaseException而不是Exception，因此不会被捕获Exception的代码意外捕获。这样可以使异常正确传播并导致解释器退出。不处理时，Python 解释器退出；否则，退出。不打印堆栈回溯。构造函数接受传递给sys.exit()的相同可选参数。如果该值是整数，则它指定系统退出状态(传递给 C 的exit()函数)；否则，为 0.如果是None，则退出状态为零；如果它具有另一种类型(例如字符串)，则将打印对象的值，并且退出状态为 1.

对sys.exit()的调用将转换为异常，以便可以执行清理处理程序(try语句的finally子句)，从而使调试器可以执行脚本而不会失去控制的风险。如果绝对肯定要立即退出(例如，在调用os.fork()之后的子进程中)，则可以使用os._exit()函数。

  • code

    • 传递给构造函数的退出状态或错误消息。 (默认为None.)

  • exception TypeError

    • 在将操作或Function应用于不合适类型的对象时引发。关联的值是一个字符串，提供有关类型不匹配的详细信息。

用户代码可能会引发此异常，以指示不支持并且不意图支持对对象的try操作。如果某个对象旨在支持给定的操作但尚未提供实现，则NotImplementedError是引发的适当异常。

传递错误类型的参数(例如，当期望int时传递list)应导致TypeError，但是传递错误值(例如，期望边界之外的数字)的参数应导致ValueError。

  • exception UnboundLocalError

    • 在对函数或方法中的局部变量进行引用但没有值绑定到该变量时引发。这是NameError的子类。

  • exception UnicodeError

    • 在发生与 Unicode 相关的编码或解码错误时引发。它是ValueError的子类。

UnicodeError具有描述编码或解码错误的属性。例如，err.object[err.start:err.end]给出编解码器失败的特定无效 Importing。

  • encoding

    • 引发错误的编码的名称。

  • reason

    • 描述特定编解码器错误的字符串。

  • object

    • 编解码器try编码或解码的对象。

  • start

    • object中无效数据的第一个索引。

  • end

    • object中最后一个无效数据之后的索引。

  • exception UnicodeEncodeError

    • 在编码过程中发生与 Unicode 相关的错误时引发。它是UnicodeError的子类。

  • exception UnicodeDecodeError

    • 在解码期间发生与 Unicode 相关的错误时引发。它是UnicodeError的子类。

  • exception UnicodeTranslateError

    • 在翻译过程中发生 Unicode 相关错误时引发。它是UnicodeError的子类。

  • exception ValueError

    • 当操作或函数接收到类型正确但值不合适的参数时引发，并且情况未由更精确的异常(例如IndexError)描述。

  • exception ZeroDivisionError

    • 当除法或模运算的第二个自变量为零时引发。关联值是一个字符串，指示操作数和操作的类型。

为了与以前的版本兼容，保留了以下 exception；从 Python 3.3 开始，它们是OSError的别名。

  • exception EnvironmentError

  • exception IOError

  • exception WindowsError

    • 仅在 Windows 上可用。

OS exceptions

以下异常是OSError的子类，它们会根据系统错误代码而引发。

  • exception BlockingIOError
    • 在某个操作会阻塞设置为非阻塞操作的对象(例如套接字)时触发。对应于errno EAGAIN，EALREADY，EWOULDBLOCK和EINPROGRESS。

除了OSError的那些属性外，BlockingIOError还可以具有另一个属性：

  • characters_written

    • 一个整数，包含在阻止之前写入流的字符数。当使用io模块中的缓冲 I/O 类时，此属性可用。

  • exception ChildProcessError

    • 在子进程上的操作失败时引发。对应于errno ECHILD。

  • exception ConnectionError

    • 连接相关问题的 Base Class。

子类是BrokenPipeError，ConnectionAbortedError，ConnectionRefusedError和ConnectionResetError。

  • exception BrokenPipeError

    • ConnectionError的子类，在另一端关闭时try在管道上进行写操作，或试图在已关闭进行写操作的套接字上进行写操作时引发。对应于errno EPIPE和ESHUTDOWN。

  • exception ConnectionAbortedError

    • 对等方中止连接try时引发的ConnectionError子类。对应于errno ECONNABORTED。

  • exception ConnectionRefusedError

    • 当对等方拒绝连接try时引发的ConnectionError子类。对应于errno ECONNREFUSED。

  • exception ConnectionResetError

    • 当对等方重置连接时引发的ConnectionError子类。对应于errno ECONNRESET。

  • exception FileExistsError

    • 在try创建已经存在的文件或目录时引发。对应于errno EEXIST。

  • exception FileNotFoundError

    • 在请求文件或目录但不存在时引发。对应于errno ENOENT。

  • exception InterruptedError

    • 当系统调用被传入 signal break时引发。对应于errno EINTR。

在版本 3.5 中进行了更改：现在，当 signal break系统调用时，Python 现在重试系统调用，除非 signal 处理程序引发异常(基本原理请参见 PEP 475)，而不是引发InterruptedError。

  • exception IsADirectoryError

    • 在目录上请求文件操作(例如os.remove())时引发。对应于errno EISDIR。

  • exception NotADirectoryError

    • 在非目录上请求目录操作(例如os.listdir())时引发。对应于errno ENOTDIR。

  • exception PermissionError

    • 在try在没有足够访问权限(例如文件系统权限)的情况下运行操作时引发。对应于errno EACCES和EPERM。

  • exception ProcessLookupError

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

  • exception TimeoutError

    • 当系统Function在系统级别超时时引发。对应于errno ETIMEDOUT。

3.3 版的新Function：添加了上述所有OSError个子类。

See also

PEP 3151-重做 OS 和 IO 异常层次结构

Warnings

以下 exception 用作警告类别；有关更多详细信息，请参见Warning Categories文档。

  • exception Warning

    • 警告类别的 Base Class。

  • exception UserWarning

    • 用户代码生成的警告的 Base Class。

  • exception DeprecationWarning

    • 当警告已用于其他 Python 开发人员时，这些警告的 Base Class。

  • exception PendingDeprecationWarning

    • 有关已过时且预期在 Future 不推荐使用的Function的警告的 Base Class，但目前不推荐使用。

很少使用此类，因为发出关于可能即将发生的弃用的警告并不常见，并且DeprecationWarning对于已经处于活动状态的弃用是首选。

  • exception SyntaxWarning

    • 警告有关可疑语法的 Base Class。

  • exception RuntimeWarning

    • 警告有关可疑运行时行为的 Base Class。

  • exception FutureWarning

    • 当这些警告旨在供使用 Python 编写的应用程序的finally用户使用时，这些警告的 Base Class。

  • exception ImportWarning

    • 用于警告有关模块导入中可能错误的警告的 Base Class。

  • exception UnicodeWarning

    • 与 Unicode 相关的警告的 Base Class。

  • exception BytesWarning

  • exception ResourceWarning

    • 与资源使用相关的警告的 Base Class。被默认的警告过滤器忽略。

3.2 版中的新Function。

Exception hierarchy

内置异常的类层次结构为：

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