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

28.10. 追溯 — 打印或检索堆栈回溯

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

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

该模块定义了以下功能：

traceback.print_tb(tb[, limit[, file]])

从回溯对象 tb 打印最多 limit 堆栈跟踪条目。 如果省略 limit 或 None，则打印所有条目。 如果省略 file 或 None，则输出到 sys.stderr； 否则它应该是一个打开的文件或类似文件的对象来接收输出。

traceback.print_exception(etype, value, tb[, limit[, file]])

从回溯 tb 到 文件 打印异常信息和最多 limit 堆栈跟踪条目。 这在以下方面与 print_tb() 不同： (1) 如果 tb 不是 None，则打印标题 Traceback (most recent call last):； (2) 在堆栈跟踪后打印异常 etype 和 value； (3) 如果 etype 是 SyntaxError 并且 value 具有适当的格式，它会打印出现语法错误的行，并用插入符号指示错误的大致位置.

traceback.print_exc([limit[, file]])

这是 print_exception(sys.exc_type, sys.exc_value, sys.exc_traceback, limit, file) 的简写。 （实际上，它使用 sys.exc_info() 以线程安全的方式检索相同的信息，而不是使用已弃用的变量。）

traceback.format_exc([limit])

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

2.4 版中的新功能。

traceback.print_last([limit[, file]])

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

traceback.print_stack([f[, limit[, file]]])

此函数从其调用点打印堆栈跟踪。 可选的 f 参数可用于指定要启动的备用堆栈帧。 可选的 limit 和 file 参数与 print_exception() 的含义相同。

traceback.extract_tb(tb[, limit])

返回从回溯对象 tb 中提取的最多 limit “预处理”堆栈跟踪条目的列表。 它对于堆栈跟踪的替代格式很有用。 如果省略 limit 或 None，则提取所有条目。 “预处理”堆栈跟踪条目是一个 4 元组（文件名、行号、函数名*、文本），表示通常使用的信息打印堆栈跟踪。 text 是一个去除了前导和尾随空格的字符串； 如果源不可用，则为 None。

traceback.extract_stack([f[, limit]])

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

traceback.format_list(extracted_list)

给定 extract_tb() 或 extract_stack() 返回的元组列表，返回准备打印的字符串列表。 结果列表中的每个字符串对应于参数列表中具有相同索引的项目。 每个字符串以换行符结尾； 对于源文本行不是 None 的项目，字符串也可能包含内部换行符。

traceback.format_exception_only(etype, value)

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

traceback.format_exception(etype, value, tb[, limit])

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

traceback.format_tb(tb[, limit])

format_list(extract_tb(tb, limit)) 的简写。

traceback.format_stack([f[, limit]])

format_list(extract_stack(f, limit)) 的简写。

traceback.tb_lineno(tb)

此函数返回在回溯对象中设置的当前行号。 此函数是必需的，因为在 2.3 之前的 Python 版本中，当 -O 标志传递给 Python 时，tb.tb_lineno 未正确更新。 这个函数在 2.3 以后的版本中没有用。

28.10.1。 回溯示例

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

import sys, traceback

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

envdir = {}
while 1:
    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:"
    traceback.print_exception(exc_type, exc_value, exc_traceback,
                              limit=2, file=sys.stdout)
    print "*** print_exc:"
    traceback.print_exc()
    print "*** format_exc, first and last line:"
    formatted_lines = traceback.format_exc().splitlines()
    print formatted_lines[0]
    print formatted_lines[-1]
    print "*** format_exception:"
    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:
[('<doctest...>', 10, '<module>', 'lumberjack()'),
 ('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'),
 ('<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')]
*** 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']