traceback — 打印或检索堆栈回溯

源代码： :source:`Lib/traceback.py`

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

该模块使用回溯对象——这是存储在 sys.last_traceback 变量中并作为 sys.exc_info() 的第三项返回的对象类型。

该模块定义了以下功能：

traceback.print_tb(tb, limit=None, file=None): 如果 limit 为正，则从回溯对象 tb（从调用者的帧开始）打印最多 limit 堆栈跟踪条目。否则，打印最后的 abs(limit) 条目。如果省略 limit 或 None，则打印所有条目。如果省略 file 或 None，则输出到 sys.stderr；否则它应该是一个打开的文件或类似文件的对象来接收输出。

在 3.5 版更改：添加了负限制支持。

traceback.print_exception(etype, value, tb, limit=None, file=None, chain=True)

将异常信息和堆栈跟踪条目从回溯对象 tb 打印到 file。这在以下方面与 print_tb() 不同：

如果 tb 不是 None，则打印标题 Traceback (most recent call last):
它在堆栈跟踪后打印异常 etype 和 value

如果 type(value) 是 SyntaxError 并且 value 具有适当的格式，它会打印出现语法错误的行，并用插入符号指示错误。

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

在 3.5 版更改：忽略 etype 参数并从值的类型推断。

traceback.print_exc(limit=None, file=None, chain=True): 这是 print_exception(*sys.exc_info(), limit, file, chain) 的简写。

traceback.print_last(limit=None, file=None, chain=True): 这是 print_exception(sys.last_type, sys.last_value, sys.last_traceback, limit, file, chain) 的简写。一般来说，只有在异常到达交互式提示后才会工作（参见 sys.last_type）。

traceback.print_stack(f=None, limit=None, file=None): 如果 limit 为正，则最多打印 limit 堆栈跟踪条目（从调用点开始）。否则，打印最后的 abs(limit) 条目。如果省略 limit 或 None，则打印所有条目。可选的 f 参数可用于指定要启动的备用堆栈帧。可选的 file 参数与 print_tb() 的含义相同。

在 3.5 版更改：添加了负限制支持。

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(etype, value): 格式化回溯的异常部分。参数是异常类型和值，例如由 sys.last_type 和 sys.last_value 给出。返回值是一个字符串列表，每个字符串都以换行符结尾。通常，列表包含一个字符串；但是，对于 SyntaxError 异常，它包含几行（打印时）显示有关语法错误发生位置的详细信息。指示发生哪个异常的消息始终是列表中的最后一个字符串。

traceback.format_exception(etype, value, tb, limit=None, chain=True): 格式化堆栈跟踪和异常信息。这些参数与 print_exception() 的相应参数具有相同的含义。返回值是一个字符串列表，每个字符串以换行符结尾，有些包含内部换行符。连接并打印这些行时，将打印与 print_exception() 完全相同的文本。

在 3.5 版更改：忽略 etype 参数并从值的类型推断。

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)

捕获异常以供以后渲染。 limit、lookup_lines 和 capture_locals 与 StackSummary 类相同。

请注意，当本地人被捕获时，它们也会显示在回溯中。

__cause__: 原始 __cause__ 的 TracebackException。

__context__: 原始 __context__ 的 TracebackException。

__suppress_context__: 来自原始异常的 __suppress_context__ 值。

stack: 一个 StackSummary 代表回溯。

exc_type: 原始回溯的类。

filename: 对于语法错误 - 发生错误的文件名。

lineno: 对于语法错误 - 发生错误的行号。

text: 对于语法错误 - 发生错误的文本。

offset: 对于语法错误 - 发生错误的文本的偏移量。

msg: 对于语法错误 - 编译器错误消息。

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

捕获异常以供以后渲染。 limit、lookup_lines 和 capture_locals 与 StackSummary 类相同。

请注意，当本地人被捕获时，它们也会显示在回溯中。

format(*, chain=True)

格式化异常。

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

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

指示发生哪个异常的消息始终是输出中的最后一个字符串。

format_exception_only()

格式化回溯的异常部分。

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

通常，生成器发出单个字符串；然而，对于 SyntaxError 异常，它会发出几行（打印时）显示有关语法错误发生位置的详细信息。

指示发生哪个异常的消息始终是输出中的最后一个字符串。

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 中的局部变量被捕获为对象表示。

classmethod from_list(a_list): 从提供的 FrameSummary 对象列表或旧式元组列表构造 StackSummary 对象。每个元组应该是一个以文件名、行号、名称、行为元素的 4 元组。

format()

返回准备打印的字符串列表。结果列表中的每个字符串对应于堆栈中的单个帧。每个字符串以换行符结尾；对于带有源文本行的项目，字符串也可能包含内部换行符。

对于同一帧和同一行的长序列，会显示前几次重复，然后是一个摘要行，说明进一步重复的确切次数。

3.6 版更改：重复帧的长序列现在被缩写。

FrameSummary 对象

3.5 版中的新功能。

FrameSummary 对象表示回溯中的单个帧。

class traceback.FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None): 表示正在格式化或打印的回溯或堆栈中的单个帧。它可以选择包含包含在其中的本地帧的字符串化版本。如果 lookup_line 是 False，则直到 FrameSummary 访问了 line 属性（这也会在将其转换为一个元组）。 line 可以直接提供，并且将完全防止行查找发生。 locals 是一个可选的局部变量字典，如果提供，变量表示将存储在摘要中以供以后显示。

回溯示例

这个简单的例子实现了一个基本的 read-eval-print 循环，类似于（但不如）标准的 Python 交互式解释器循环。有关解释器循环的更完整实现，请参阅 code 模块。

import sys, traceback

def run_user_code(envdir):
    source = input(">>> ")
    try:
        exec(source, envdir)
    except Exception:
        print("Exception in user code:")
        print("-"*60)
        traceback.print_exc(file=sys.stdout)
        print("-"*60)

envdir = {}
while True:
    run_user_code(envdir)

以下示例演示了打印和格式化异常和回溯的不同方法：

import sys, traceback

def lumberjack():
    bright_side_of_death()

def bright_side_of_death():
    return tuple()[0]

try:
    lumberjack()
except IndexError:
    exc_type, exc_value, exc_traceback = sys.exc_info()
    print("*** print_tb:")
    traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)
    print("*** print_exception:")
    # exc_type below is ignored on 3.5 and later
    traceback.print_exception(exc_type, exc_value, exc_traceback,
                              limit=2, file=sys.stdout)
    print("*** print_exc:")
    traceback.print_exc(limit=2, file=sys.stdout)
    print("*** format_exc, first and last line:")
    formatted_lines = traceback.format_exc().splitlines()
    print(formatted_lines[0])
    print(formatted_lines[-1])
    print("*** format_exception:")
    # exc_type below is ignored on 3.5 and later
    print(repr(traceback.format_exception(exc_type, exc_value,
                                          exc_traceback)))
    print("*** extract_tb:")
    print(repr(traceback.extract_tb(exc_traceback)))
    print("*** format_tb:")
    print(repr(traceback.format_tb(exc_traceback)))
    print("*** tb_lineno:", exc_traceback.tb_lineno)

该示例的输出类似于以下内容：

*** print_tb:
  File "<doctest...>", line 10, in <module>
    lumberjack()
*** print_exception:
Traceback (most recent call last):
  File "<doctest...>", line 10, in <module>
    lumberjack()
  File "<doctest...>", line 4, in lumberjack
    bright_side_of_death()
IndexError: tuple index out of range
*** print_exc:
Traceback (most recent call last):
  File "<doctest...>", line 10, in <module>
    lumberjack()
  File "<doctest...>", line 4, in lumberjack
    bright_side_of_death()
IndexError: tuple index out of range
*** format_exc, first and last line:
Traceback (most recent call last):
IndexError: tuple index out of range
*** format_exception:
['Traceback (most recent call last):\n',
 '  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
 '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
 '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\n',
 'IndexError: tuple index out of range\n']
*** extract_tb:
[<FrameSummary file <doctest...>, line 10 in <module>>,
 <FrameSummary file <doctest...>, line 4 in lumberjack>,
 <FrameSummary file <doctest...>, line 7 in bright_side_of_death>]
*** format_tb:
['  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
 '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
 '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\n']
*** tb_lineno: 10

以下示例显示了打印和格式化堆栈的不同方法：

>>> import traceback
>>> def another_function():
...     lumberstack()
...
>>> def lumberstack():
...     traceback.print_stack()
...     print(repr(traceback.extract_stack()))
...     print(repr(traceback.format_stack()))
...
>>> another_function()
  File "<doctest>", line 10, in <module>
    another_function()
  File "<doctest>", line 3, in another_function
    lumberstack()
  File "<doctest>", line 6, in lumberstack
    traceback.print_stack()
[('<doctest>', 10, '<module>', 'another_function()'),
 ('<doctest>', 3, 'another_function', 'lumberstack()'),
 ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')]
['  File "<doctest>", line 10, in <module>\n    another_function()\n',
 '  File "<doctest>", line 3, in another_function\n    lumberstack()\n',
 '  File "<doctest>", line 8, in lumberstack\n    print(repr(traceback.format_stack()))\n']

最后一个示例演示了最后几个格式化函数：

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

traceback — 打印或检索堆栈回溯 — Python 文档

目录

traceback — 打印或检索堆栈回溯

TracebackException 对象

StackSummary 对象

FrameSummary 对象

回溯示例