traceback
---打印或检索堆栈回溯¶
源代码: 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 版更改: 添加了负数 limit 支持。
- traceback.print_exception(exc, /, [value, tb, ]limit=None, file=None, chain=True)¶
从跟踪对象打印异常信息和堆栈跟踪条目 tb 到 file . 这与
print_tb()
方法如下:如果 tb 不是
None
,它打印一个标题Traceback (most recent call last):
它打印异常类型并 价值 在堆栈跟踪之后
如果 类型(值) 是
SyntaxError
和 value 具有适当的格式,它打印发生语法错误的行,并用一个插入符号指示错误的大致位置。
从Python3.10开始,不是传递 价值 和 tb 异常对象可以作为第一个参数传递。如果 价值 和 tb 时,将忽略第一个参数以提供向后兼容性。
可选的 limit 参数的含义与for相同
print_tb()
.如果 链 为真(默认),然后链接异常(__cause__
或__context__
异常的属性)也将被打印,就像在打印未处理的异常时解释器本身一样。在 3.5 版更改: 这个 埃特佩 参数被忽略并从 value .
在 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 参数的含义与for相同print_tb()
.在 3.5 版更改: 添加了负数 limit 支持。
- traceback.extract_tb(tb, limit=None)¶
返回A
StackSummary
对象,表示从跟踪对象中提取的“预处理”堆栈跟踪项列表 tb . 它对于堆栈跟踪的交替格式化很有用。可选的 limit 参数的含义与for相同print_tb()
. “预处理”堆栈跟踪条目是FrameSummary
包含属性的对象filename
,lineno
,name
和line
表示通常为堆栈跟踪而打印的信息。这个line
是一个去掉前导和尾随空格的字符串;如果源不可用,则为None
.
- traceback.extract_stack(f=None, limit=None)¶
从当前堆栈帧中提取原始跟踪。返回值的格式与for相同
extract_tb()
. 可选的 f 和 limit 参数的含义与print_stack()
.
- traceback.format_list(extracted_list)¶
给定元组列表或
FrameSummary
返回的对象extract_tb()
或extract_stack()
,返回准备打印的字符串列表。结果列表中的每个字符串对应于参数列表中索引相同的项。每个字符串以换行符结尾;对于源文本行不是的项,字符串也可以包含内部换行符。None
.
- traceback.format_exception_only(exc, /[, value])¶
使用异常值(如由给定的)设置回溯的异常部分的格式
sys.last_value
。返回值是一个字符串列表,每个字符串都以换行符结尾。通常,列表包含单个字符串;但是,对于SyntaxError
异常,它包含几行(打印时)显示有关语法错误发生位置的详细信息。指示发生的异常的消息始终是列表中的最后一个字符串。从Python3.10开始,不是传递 价值 异常对象可以作为第一个参数传递。如果 价值 则忽略第一个参数,以便提供向后兼容性。
在 3.10 版更改: 这个 Etype 参数已重命名为 exc 并且现在仅限于位置。
- traceback.format_exception(exc, /, [value, tb, ]limit=None, chain=True)¶
格式化堆栈跟踪和异常信息。这些参数的含义与
print_exception()
. 返回值是一个字符串列表,每个字符串以换行符结尾,一些字符串包含内部换行符。当这些行连接并打印时,打印的文本与打印的文本完全相同print_exception()
.在 3.5 版更改: 这个 埃特佩 参数被忽略并从 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)¶
清除回溯中所有堆栈帧的局部变量 tb 通过调用
clear()
每个帧对象的方法。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
类。如果 紧凑型 为真,则只有
TracebackException
%sformat
方法保存在类属性中。特别值得一提的是,__context__
字段仅在以下情况下计算__cause__
是None
和__suppress_context__
是假的。注意,当捕获局部变量时,它们也会显示在回溯中。
- __cause__¶
A
TracebackException
原始的__cause__
.
- __context__¶
A
TracebackException
原始的__context__
.
- __suppress_context__¶
这个
__suppress_context__
原始异常的值。
- stack¶
A
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)¶
格式化异常。
如果 链 不是
True
,__cause__
和__context__
将不格式化。返回值是字符串的生成器,每个字符串以换行符结尾,一些字符串包含内部换行符。
print_exception()
是围绕此方法的封装器,它只将行打印到文件中。指示发生异常的消息始终是输出中的最后一个字符串。
- format_exception_only()¶
设置追溯的异常部分的格式。
返回值是字符串的生成器,每个字符串以换行符结尾。
通常,生成器会发出一个字符串;但是,对于
SyntaxError
异常情况下,它会发出几行(打印时)显示有关语法错误发生位置的详细信息。指示发生异常的消息始终是输出中的最后一个字符串。
在 3.10 版更改: 添加了 紧凑型 参数。
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)¶
构建一个
StackSummary
提供的列表中的对象FrameSummary
对象或元组的旧样式列表。每个元组应该是一个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打印循环,类似于(但不如)标准的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']