traceback —— 打印或读取堆栈的跟踪信息

源代码： Lib/traceback.py

该模块提供了一个标准接口来提取、格式化和打印 Python 程序的堆栈跟踪结果。它完全模仿Python 解释器在打印堆栈跟踪结果时的行为。当您想要在程序控制下打印堆栈跟踪结果时，例如在“封装”解释器时，这是非常有用的。

本模块使用回溯对象 —- 它们是类型为 types.TracebackType 的对象，将被赋值给 BaseException 实例的 __traceback__ 字段。

参见

模块 faulthandler

用于在发生错误、超时或用户信号时显式地转储 Python 回溯信息。

模块 pdb

用于 Python 程序的交互式源代码调试器。

这个模块定义了以下函数：

traceback.print_tb(tb, limit=None, file=None)

如果*limit*是正整数，那么从 traceback 对象 “tb” 输出最高 limit 个（从调用函数开始的）栈的堆栈回溯‎条目‎；如果 limit 是负数就输出 abs(limit) 个回溯条目；又如果 limit 被省略或者为 None ，那么就会输出所有回溯条目。如果 file 被省略或为 None 那么就会输出至标准输出 sys.stderr 否则它应该是一个打开的文件或者文件类对象来接收输出

在 3.5 版更改: 添加了对负数值 limit 的支持

traceback.print_exception(exc, /, [value, tb, ]limit=None, file=None, chain=True)

打印回溯对象 tb 到 file 的异常信息和整个堆栈回溯。这和 print_tb() 比有以下方面不同：

  • 如果 tb 不为 None，它将打印头部 Traceback (most recent call last):

  • 它将在栈回溯之后打印异常类型和 value

  • 如果 type(value) 为 SyntaxError 且 value 具有适当的格式，它会打印发生语法错误的行并用一个圆点来指明错误的大致位置。

从 Python 3.10 开始，可以不再传递 value 和 tb，而是传递一个异常对象作为第一个参数。 如果提供了 value 和 tb，则第一个参数会被忽略以便提供向下兼容性。

可选的 limit 参数具有与 print_tb() 的相同含义。 如果 chain 为真值（默认），则链式异常（异常的 __cause__ 或 __context__ 属性）也将被打印出来，就像解释器本身在打印未处理的异常时一样。

在 3.5 版更改: etype 参数会被忽略并根据 value 推断出来。

在 3.10 版更改: etype 形参已被重命名为 exc 并且现在是仅限位置形参。

traceback.print_exc(limit=None, file=None, chain=True)

这是 print_exception(sys.exception(), limit, file, chain) 的快捷操作。

traceback.print_last(limit=None, file=None, chain=True)

这是 print_exception(sys.last_exc, limit, file, chain) 的一个快捷方式。 通常它将只在异常到达交互提示符之后才会起作用 (参见 sys.last_exc)。

traceback.print_stack(f=None, limit=None, file=None)

如果 limit 为正数则打印至多 limit 个栈回溯条目（从发起调用点开始）。 在其他情况下，则打印最后 abs(limit) 个条目。 如果 limit 被省略或为 None，则会打印所有条目。 可选的 f 参数可被用来指明一个用于开始的替代栈。 可选的 file 参数具有与 print_tb() 的相同含义。

在 3.5 版更改: 添加了对负数值 limit 的支持

traceback.extract_tb(tb, limit=None)

返回一个 StackSummary 对象来代表从回溯对象 tb 提取的 “预处理” 栈回溯条目列表。 它适用于栈回溯的替代格式化。 可选的 limit 参数具有与 print_tb() 的相同含义。 “预处理” 栈回溯条目是一个 FrameSummary 对象，其中包含代表通常为栈回溯打印的信息的 filename, lineno, name 和 line 等属性。 line 是一个去除了前导和末尾空白符的字符串；如果源代码不可用则它将为 None。

traceback.extract_stack(f=None, limit=None)

从当前的栈帧提取原始回溯信息。 返回值具有与 extract_tb() 的相同格式。 可选的 f 和 limit 参数具有与 print_stack() 的相同含义。

traceback.format_list(extracted_list)

给定一个由元组或如 extract_tb() 或 extract_stack() 所返回的 FrameSummary 对象组成的列表，返回一个可打印的字符串列表。 结果列表中的每个字符串都对应于参数列表中具有相同索引号的条目。 每个字符串以一个换行符结束；对于那些源文本行不为 None 的条目，字符串也可能包含内部换行符。

traceback.format_exception_only(exc, /[, value])

使用 sys.last_value 等给出的异常值来格式化回溯中的异常部分。 返回值是一个字符串的列表，每个字符串都以换行符结束。 该列表包含异常消息，它通常是一个字符串；但是，对于 SyntaxError 异常，它将包含多行并且（当打印时）会显示语法错误发生位置的详细信息。 在异常消息之后，该列表还包含了异常的 注释。

从 Python 3.10 开始，可以不传入 value，而是传入一个异常对象作为第一个参数。 如果提供了 value，则第一个参数将被忽略以便提供向下兼容性。

在 3.10 版更改: etype 形参已被重命名为 exc 并且现在是仅限位置形参。

在 3.11 版更改: 返回的列表现在包括关联到异常的任何注释。

traceback.format_exception(exc, /, [value, tb, ]limit=None, chain=True)

格式化一个栈跟踪和异常信息。 参数的含义与传给 print_exception() 的相应参数相同。 返回值是一个字符串列表，每个字符串都以一个换行符结束且有些还包含内部换行符。 当这些行被拼接并打印时，打印的文本与 print_exception() 的完全相同。

在 3.5 版更改: etype 参数会被忽略并根据 value 推断出来。

在 3.10 版更改: 此函数的行为和签名已被修改以与 print_exception() 相匹配。

traceback.format_exc(limit=None, chain=True)

这类似于 print_exc(limit) 但会返回一个字符串而不是打印到一个文件。

traceback.format_tb(tb, limit=None)

是 format_list(extract_tb(tb, limit)) 的简写形式。

traceback.format_stack(f=None, limit=None)

是 format_list(extract_stack(f, limit)) 的简写形式。

traceback.clear_frames(tb)

通过调用每个帧对象的 clear() 方法来清除回溯 tb 中所有栈帧的局部变量。

3.4 新版功能.

traceback.walk_stack(f)

从给定的帧开始访问 f.f_back 之后的栈，产生每一帧的帧和行号。 如果 f 为 None，则会使用当前栈。 这个辅助函数要与 StackSummary.extract() 一起使用。

3.5 新版功能.

traceback.walk_tb(tb)

访问 tb_next 之后的回溯并产生每一帧的帧和行号。 这个辅助函数要与 StackSummary.extract() 一起使用。

3.5 新版功能.

此模块还定义了以下的类:

TracebackException 对象

3.5 新版功能.

TracebackException 对象基于实际的异常创建通过轻量的方式捕获数据以便随后打印。

class traceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)

捕获一个异常以便随后渲染。 limit, lookup_lines 和 capture_locals 的含义与 StackSummary 类的相同。

如果 compact 为真值，则只有 TracebackException 的 format 方法所需要的数据会被保存在类属性中。 特别地，__context__ 字段只有在 __cause__ 为 None 且 __suppress_context__ 为假值时才会被计算。

请注意当局部变量被捕获时，它们也会被显示在回溯中。

max_group_width 和 max_group_depth 控制异常组的格式化 (参见 BaseExceptionGroup)。 depth 是指分组的嵌套层级，而 width 是指一个异常组的异常数组的大小。 格式化的输出在达到某个限制时将被截断。

在 3.10 版更改: 增加了 compact 形参。

在 3.11 版更改: 添加了 max_group_width 和 max_group_depth 形参。parameters.

  • __cause__

    原始 __cause__ 的 TracebackException。

  • __context__

    原始 __context__ 的 TracebackException。

  • exceptions

    如果 self 代表一个 ExceptionGroup，此字段将保存一个由代表被嵌套异常的 TracebackException 实例组成的列表。 否则它将为 None。

    3.11 新版功能.

  • __suppress_context__

    来自原始异常的 __suppress_context__。

  • __notes__

    来自原始异常的 __notes__ 值，或者如果异常没有任何注解则为 None。 如果它不为 None 则会在异常字符串的回溯之后进行格式化。

    3.11 新版功能.

  • stack

    代表回溯的 StackSummary。

  • exc_type

    原始回溯的类。

  • filename

    针对语法错误 —— 错误发生所在的文件名。

  • lineno

    针对语法错误 —— 错误发生所在的行号。

  • end_lineno

    针对语法错误 —— 错误发生所在的末尾行号。 如不存在则可以为 None。

    3.10 新版功能.

  • text

    针对语法错误 —— 错误发生所在的文本。

  • offset

    针对语法错误 —— 错误发生所在的文本内部的偏移量。

  • end_offset

    针对语法错误 —— 错误发生所在的文本末尾偏移量。 如不存在则可以为 None。

    3.10 新版功能.

  • msg

    针对语法错误 —— 编译器错误消息。

  • classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)

    捕获一个异常以便随后渲染。 limit, lookup_lines 和 capture_locals 的含义与 StackSummary 类的相同。

    请注意当局部变量被捕获时，它们也会被显示在回溯中。

  • print(*, file=None, chain=True)

    将 format() 所返回的异常信息打印至 file (默认为 sys.stderr)。

    3.11 新版功能.

  • format(*, chain=True)

    格式化异常。

    如果 chain 不为 True，则 __cause__ 和 __context__ 将不会被格式化。

    返回值是一个字符串的生成器，其中每个字符串都以换行符结束并且有些还会包含内部换行符。 print_exception() 是此方法的一个包装器，它只是将这些行打印到一个文件。

  • format_exception_only()

    格式化回溯的异常部分。

    返回值是一个字符串的生成器，每个字符串都以一个换行符结束。

    生成器会发出异常消息并附带其注释（如果有注释的话）。 异常消息通常是一个字符串；但是，对于 SyntaxError 异常，它将包含多行并且（当打印时）会显示语法错误发生位置的详细信息。

    在 3.11 版更改: 异常的注释现在将被包括在输出中。

StackSummary 对象

3.5 新版功能.

代表一个可被格式化的调用栈的 StackSummary 对象。

class traceback.StackSummary

  • classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)

    构造一个来自帧生成器的 StackSummary 对象（如 walk_stack() 或 walk_tb() 所返回的一样）。

    如果提供了 limit，则只从 frame_gen 提取指定数量的帧。 如果 lookup_lines 为 False，则返回的 FrameSummary 对象将不会读入它们的行，这使得创建 StackSummary 的开销更低（如果它不会被实际格式化这就会很有价值）。 如果 capture_locals 为 True 则每个 FrameSummary 中的局部变量会被捕获为对象表示形式。

    在 3.12 版更改: 在局部变量的 repr() 上被引发的异常（当 capture_locals 为 True 时）不会再被传播给调用方。

  • classmethod from_list(a_list)

    从所提供的 FrameSummary 对象列表或旧式的元组列表构造一个 StackSummary 对象。 每个元组都应当是以文件、行号、名称和行为元素的 4 元组。

  • format()

    返回一个可打印的字符串列表。 结果列表中的每个字符串各自对应来自于栈的单独帧。 每个字符串都以一个换行符结束；对于带有源文本行的条目来说，字符串还可能包含内部换行符。

    对于同一帧与行的长序列，将显示前几个重复项，后面跟一个指明之后的实际重复次数的摘要行。

    在 3.6 版更改: 重复帧的长序列现在将被缩减。

  • format_frame_summary(frame_summary)

    返回用于打印栈中涉及的某一帧的字符串。 此方法会为每个要用 StackSummary.format() 来打印的 FrameSummary 对象进行调用。 如果它返回 None，该帧将从输出中被省略。

    3.11 新版功能.

FrameSummary 对象

3.5 新版功能.

FrameSummary 对象代表回溯中的一个单独帧。

class traceback.FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)

代表回溯或栈中被格式化或打印的一个单独帧。 它有时可能还带有包括在其中的帧局部变量的字符串化版本。 如果 lookup_line 为 False，则不会查找源代码直到 FrameSummary 已经访问了 line 属性（这还将发生在将其转换为元组时）。 line 可能会被直接提供，并将完全阻止行查找的发生。 locals 是一个可选的局部变量字典，如果有提供的话这些变量的表示形式将被存储在摘要中以便随后显示。

回溯示例

这个简单示例是一个基本的读取-求值-打印循环，类似于（但实用性小于）标准 Python 交互式解释器循环。 对于解释器循环的更完整实现，请参阅 code 模块。

  1. import sys, traceback
  3. def run_user_code(envdir):
  4.     source = input(">>> ")
  5.     try:
  6.         exec(source, envdir)
  7.     except Exception:
  8.         print("Exception in user code:")
  9.         print("-"*60)
  10.         traceback.print_exc(file=sys.stdout)
  11.         print("-"*60)
  13. envdir = {}
  14. while True:
  15.     run_user_code(envdir)

下面的例子演示了打印和格式化异常与回溯的不同方式:

  1. import sys, traceback
  3. def lumberjack():
  4.     bright_side_of_life()
  6. def bright_side_of_life():
  7.     return tuple()[0]
  9. try:
  10.     lumberjack()
  11. except IndexError:
  12.     exc = sys.exception()
  13.     print("*** print_tb:")
  14.     traceback.print_tb(exc.__traceback__, limit=1, file=sys.stdout)
  15.     print("*** print_exception:")
  16.     traceback.print_exception(exc, limit=2, file=sys.stdout)
  17.     print("*** print_exc:")
  18.     traceback.print_exc(limit=2, file=sys.stdout)
  19.     print("*** format_exc, first and last line:")
  20.     formatted_lines = traceback.format_exc().splitlines()
  21.     print(formatted_lines[0])
  22.     print(formatted_lines[-1])
  23.     print("*** format_exception:")
  24.     print(repr(traceback.format_exception(exc)))
  25.     print("*** extract_tb:")
  26.     print(repr(traceback.extract_tb(exc.__traceback__)))
  27.     print("*** format_tb:")
  28.     print(repr(traceback.format_tb(exc.__traceback__)))
  29.     print("*** tb_lineno:", exc.__traceback__.tb_lineno)

该示例的输出看起来像是这样的:

  1. *** print_tb:
  2.   File "<doctest...>", line 10, in <module>
  3.     lumberjack()
  4. *** print_exception:
  5. Traceback (most recent call last):
  6.   File "<doctest...>", line 10, in <module>
  7.     lumberjack()
  8.   File "<doctest...>", line 4, in lumberjack
  9.     bright_side_of_life()
  10. IndexError: tuple index out of range
  11. *** print_exc:
  12. Traceback (most recent call last):
  13.   File "<doctest...>", line 10, in <module>
  14.     lumberjack()
  15.   File "<doctest...>", line 4, in lumberjack
  16.     bright_side_of_life()
  17. IndexError: tuple index out of range
  18. *** format_exc, first and last line:
  19. Traceback (most recent call last):
  20. IndexError: tuple index out of range
  21. *** format_exception:
  22. ['Traceback (most recent call last):\n',
  23.  '  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n',
  24.  '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n',
  25.  '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n',
  26.  'IndexError: tuple index out of range\n']
  27. *** extract_tb:
  28. [<FrameSummary file <doctest...>, line 10 in <module>>,
  29.  <FrameSummary file <doctest...>, line 4 in lumberjack>,
  30.  <FrameSummary file <doctest...>, line 7 in bright_side_of_life>]
  31. *** format_tb:
  32. ['  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n',
  33.  '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n',
  34.  '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n']
  35. *** tb_lineno: 10

下面的例子演示了打印和格式化栈的不同方式:

  1. >>> import traceback
  2. >>> def another_function():
  3. ...     lumberstack()
  4. ...
  5. >>> def lumberstack():
  6. ...     traceback.print_stack()
  7. ...     print(repr(traceback.extract_stack()))
  8. ...     print(repr(traceback.format_stack()))
  9. ...
  10. >>> another_function()
  11.   File "<doctest>", line 10, in <module>
  12.     another_function()
  13.   File "<doctest>", line 3, in another_function
  14.     lumberstack()
  15.   File "<doctest>", line 6, in lumberstack
  16.     traceback.print_stack()
  17. [('<doctest>', 10, '<module>', 'another_function()'),
  18.  ('<doctest>', 3, 'another_function', 'lumberstack()'),
  19.  ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')]
  20. ['  File "<doctest>", line 10, in <module>\n    another_function()\n',
  21.  '  File "<doctest>", line 3, in another_function\n    lumberstack()\n',
  22.  '  File "<doctest>", line 8, in lumberstack\n    print(repr(traceback.format_stack()))\n']

最后这个例子演示了最后几个格式化函数:

  1. >>> import traceback
  2. >>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
  3. ...                        ('eggs.py', 42, 'eggs', 'return "bacon"')])
  4. ['  File "spam.py", line 3, in <module>\n    spam.eggs()\n',
  5.  '  File "eggs.py", line 42, in eggs\n    return "bacon"\n']
  6. >>> an_error = IndexError('tuple index out of range')
  7. >>> traceback.format_exception_only(type(an_error), an_error)
  8. ['IndexError: tuple index out of range\n']