traceback — 打印或检索堆栈回溯 — Python 文档
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(exc, /, [value, tb, ]limit=None, file=None, chain=True)
将异常信息和堆栈跟踪条目从回溯对象 tb 打印到 file。 这在以下方面与 print_tb() 不同:
如果 tb 不是
None
,则打印标题Traceback (most recent call last):
它在堆栈跟踪后打印异常类型和 值
如果 type(value) 是 SyntaxError 并且 value 具有适当的格式,它会打印出现语法错误的行,并用插入符号指示错误。
从 Python 3.10 开始,可以将异常对象作为第一个参数传递,而不是传递 value 和 tb。 如果提供了 value 和 tb,则忽略第一个参数以提供向后兼容性。
可选的 limit 参数与 print_tb() 的含义相同。 如果 chain 为真(默认值),那么链式异常(异常的
__cause__
或__context__
属性)也会被打印出来,就像解释器本身在打印未处理的异常。在 3.5 版更改:忽略 etype 参数并从 值 的类型推断。
3.10 版更改: etype 参数已重命名为 exc,现在仅是位置参数。
- 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(exc, /[, value])
使用异常值(例如由
sys.last_value
给出)格式化回溯的异常部分。 返回值是一个字符串列表,每个字符串都以换行符结尾。 通常,列表包含一个字符串; 但是,对于 SyntaxError 异常,它包含几行(打印时)显示有关语法错误发生位置的详细信息。 指示发生哪个异常的消息始终是列表中的最后一个字符串。从 Python 3.10 开始,可以将异常对象作为第一个参数传递,而不是传递 值 。 如果提供 value,则忽略第一个参数以提供向后兼容性。
3.10 版更改: etype 参数已重命名为 exc,现在仅是位置参数。
- traceback.format_exception(exc, /, [value, tb, ]limit=None, chain=True)
格式化堆栈跟踪和异常信息。 这些参数与 print_exception() 的相应参数具有相同的含义。 返回值是一个字符串列表,每个字符串以换行符结尾,有些包含内部换行符。 连接并打印这些行时,将打印与 print_exception() 完全相同的文本。
在 3.5 版更改:忽略 etype 参数并从 值 的类型推断。
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)
捕获异常以供以后渲染。 limit、lookup_lines 和 capture_locals 与 StackSummary 类相同。
如果 compact 为 true,则只有 TracebackException 的
format
方法需要的数据才会保存在类属性中。 特别地,仅当__cause__
为None
且__suppress_context__
为假时,才会计算__context__
字段。请注意,当本地人被捕获时,它们也会显示在回溯中。
- __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 异常,它会发出几行(打印时)显示有关语法错误发生位置的详细信息。
指示发生哪个异常的消息始终是输出中的最后一个字符串。
3.10 版更改: 添加 compact 参数。
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']