traceback

traceback - 打印或检索堆栈追溯

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

模块使用跟踪对象 - 这是存储在变量sys.exc_traceback（不建议使用）和sys.last_traceback中并作为sys.exc_info（）的第三项返回的对象类型。

该模块定义了以下功能：

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

打印以限制回溯对象tb的堆栈跟踪条目。如果省略限制或无，则打印所有条目。如果省略文件或无，则输出转到sys.stderr; 否则它应该是一个打开的文件或文件类对象来接收输出。

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

打印异常信息，并将traceback tb中的堆栈跟踪条目限制为文件。这与print_tb（）有以下不同之处：（1）如果tb不是None，它将打印一个标题Traceback（最近一次调用最后一个）; （2）在堆栈跟踪之后打印异常etype和值; （3）如果etype为SyntaxError且值的格式适当，则会打印出发生语法错误的行，并使用脱字符指示错误的大概位置。

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参数可用于指定要启动的备用堆栈帧。可选的限制*和文件参数与print_exception（）具有相同的含义。

traceback.extract_tb(tb[, limit])

返回一个列表，最多可以限制从回溯对象tb中提取的“预处理”堆栈跟踪条目。这对堆栈跟踪的替代格式非常有用。如果限制被忽略或无，所有条目被提取。 “预处理”堆栈跟踪条目是一个4元组（文件名，行号，函数名称*，文本），表示通常为堆栈跟踪打印的信息。该文本是一个带有前导和尾随空白字符的字符串; 如果源不可用，则为无。

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和值，例如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版以后没有用。

1.追溯示例

这个简单的例子实现了一个基本的读取 - 评估 - 打印循环，与标准的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']