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)

从跟踪对象打印异常信息和堆栈跟踪条目 tbfile . 这与 print_tb() 方法如下:

  • 如果 tb 不是 None ,它打印一个标题 Traceback (most recent call last):

  • 它打印异常类型并 价值 在堆栈跟踪之后

  • 如果 类型(值)SyntaxErrorvalue 具有适当的格式,它打印发生语法错误的行,并用一个插入符号指示错误的大致位置。

从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 包含属性的对象 filenamelinenonameline 表示通常为堆栈跟踪而打印的信息。这个 line 是一个去掉前导和尾随空格的字符串;如果源不可用,则为 None .

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

从当前堆栈帧中提取原始跟踪。返回值的格式与for相同 extract_tb() . 可选的 flimit 参数的含义与 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 从给定的帧,生成每个帧的帧和行号。如果 fNone ,使用当前堆栈。此助手用于 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)

捕获一个异常以供以后呈现。 limitlookup_linescapture_locals 至于 StackSummary 类。

如果 紧凑型 为真,则只有 TracebackException %s format 方法保存在类属性中。特别值得一提的是, __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)

捕获一个异常以供以后呈现。 limitlookup_linescapture_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_linesFalse ,归来的 FrameSummary 对象尚未读入其行,因此创建 StackSummary 更便宜(如果不是真正格式化的话可能很有价值)。如果 capture_localsTrue 每个变量中的局部变量 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_lineFalse ,直到 FrameSummaryline 访问的属性(在将其强制转换为元组时也会发生这种情况)。 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']