28.10. traceback-打印或检索堆栈 traceback

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

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

该模块定义了以下Function:

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

    • 从回溯对象* tb 最多打印 limit 个堆栈跟踪条目。如果Ellipsis limit None,则将打印所有条目。如果Ellipsis file *或None,则输出转到sys.stderr;否则,它应该是一个打开的文件或类似文件的对象以接收输出。
  • traceback. print_exception(* etype value tb * [,* limit * [,* file *]])

    • 从回溯* tb file 打印异常信息和最多 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 版的新Function。

  • 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 个“已预处理”堆栈跟踪条目的列表。对于堆栈跟踪的备用格式很有用。如果Ellipsis limit None,则提取所有条目。 “预处理的”堆栈跟踪条目是一个 4Tuples( filename 行号,函数名称,* text *),代表通常为堆栈跟踪打印的信息。 * text *是一个字符串,前面和后面的空格都被去除了;如果源不可用,则为None
  • traceback. extract_stack([* f * [,* limit *]])

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

    • 给定extract_tb()extract_stack()返回的 Tuples 列表,返回准备打印的字符串列表。结果列表中的每个字符串都对应于参数列表中具有相同索引的项目。每个字符串以换行符结尾;对于源文本行不是None的那些项目,字符串也可以包含内部换行符。
  • traceback. format_exception_only(* etype value *)

    • 格式化回溯的异常部分。参数是异常类型* etype value *,例如sys.last_typesys.last_value给出的。返回值是一个字符串列表,每个字符串都以换行符结尾。通常,列表只包含一个字符串。但是,对于SyntaxErrorexception,它包含多行(在打印时)显示有关语法错误发生位置的详细信息。指示发生哪个异常的消息是列表中总是最后一个字符串。
  • 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 *)

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

28.10.1. traceback 示例

这个简单的示例实现了一个基本的 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']

最后一个示例演示了最后几个格式化Function:

>>> 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']