29.9. `traceback` — 打印或检索堆栈回溯 ¶

源代码： Lib/traceback.py

此模块提供标准接口以提取、格式化和打印 Python 程序的堆栈跟踪。它准确模仿 Python 解释器的行为，当打印堆栈跟踪时。这很有用当想要在程序控制下打印堆栈跟踪时，譬如作为在围绕解释器的包裹器。

模块使用回溯对象 — 这种对象类型存储在 sys.last_traceback 变量，且作为第 3 项返回，来自 sys.exc_info() .

模块定义了下列函数：

traceback. print_tb ( tb , limit=None , file=None ) ¶

traceback. print_exception ( etype , value , tb , limit=None , file=None , chain=True ) ¶

traceback. print_exc ( limit=None , file=None , chain=True ) ¶

traceback. print_last ( limit=None , file=None , chain=True ) ¶

traceback. print_stack ( f=None , limit=None , file=None ) ¶

traceback. extract_tb ( tb , limit=None ) ¶

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

traceback. format_list ( extracted_list ) ¶

traceback. format_exception_only ( etype , value ) ¶

traceback. format_exception ( etype , value , tb , limit=None , chain=True ) ¶

traceback. format_exc ( limit=None , chain=True ) ¶

traceback. format_tb ( tb , limit=None ) ¶

traceback. format_stack ( f=None , limit=None ) ¶

traceback. clear_frames ( tb ) ¶

traceback. walk_stack ( f ) ¶

traceback. walk_tb ( tb ) ¶

模块还定义了下列类：

29.9.1. `TracebackException` 对象 ¶

3.5 版新增。

TracebackException objects are created from actual exceptions to capture data for later printing in a lightweight fashion.

class traceback. TracebackException ( exc_type , exc_value , exc_traceback , * , limit=None , lookup_lines=True , capture_locals=False ) ¶

__cause__ ¶

__context__ ¶

__suppress_context__ ¶

stack ¶

exc_type ¶

filename ¶

lineno ¶

text ¶

offset ¶: For syntax errors - the offset into the text where the error occurred.

msg ¶: For syntax errors - the compiler error message.

classmethod from_exception ( exc , * , limit=None , lookup_lines=True , capture_locals=False ) ¶

Capture an exception for later rendering. limit , lookup_lines and capture_locals are as for the StackSummary 类。

Note that when locals are captured, they are also shown in the traceback.

format ( * , chain=True ) ¶

Format the exception.

若 chain 不是 True , __cause__ and __context__ will not be formatted.

The return value is a generator of strings, each ending in a newline and some containing internal newlines. print_exception() is a wrapper around this method which just prints the lines to a file.

The message indicating which exception occurred is always the last string in the output.

format_exception_only ( ) ¶

Format the exception part of the traceback.

The return value is a generator of strings, each ending in a newline.

Normally, the generator emits a single string; however, for SyntaxError exceptions, it emits several lines that (when printed) display detailed information about where the syntax error occurred.

The message indicating which exception occurred is always the last string in the output.

29.9.2. `StackSummary` 对象 ¶

3.5 版新增。

StackSummary objects represent a call stack ready for formatting.

class traceback. StackSummary ¶

classmethod extract ( frame_gen , * , limit=None , lookup_lines=True , capture_locals=False ) ¶

构造 StackSummary object from a frame generator (such as is returned by walk_stack() or walk_tb() ).

若 limit is supplied, only this many frames are taken from frame_gen 。若 lookup_lines is False , the returned FrameSummary objects will not have read their lines in yet, making the cost of creating the StackSummary cheaper (which may be valuable if it may not actually get formatted). If capture_locals is True the local variables in each FrameSummary are captured as object representations.

classmethod from_list ( a_list ) ¶: 构造 StackSummary object from a supplied old-style list of tuples. Each tuple should be a 4-tuple with filename, lineno, name, line as the elements.

29.9.3. `FrameSummary` 对象 ¶

3.5 版新增。

FrameSummary 对象表示单个回溯帧。

class traceback. FrameSummary ( filename , lineno , name , lookup_line=True , locals=None , line=None ) ¶: Represent a single frame in the traceback or stack that is being formatted or printed. It may optionally have a stringified version of the frames locals included in it. If lookup_line is False , the source code is not looked up until the FrameSummary 拥有 line attribute accessed (which also happens when casting it to a tuple). line may be directly provided, and will prevent line lookups happening at all. locals is an optional local variable dictionary, and if supplied the variable representations are stored in the summary for later display.

29.9.4. 回溯范例 ¶

This simple example implements a basic read-eval-print loop, similar to (but less useful than) the standard Python interactive interpreter loop. For a more complete implementation of the interpreter loop, refer to the 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)

The following example demonstrates the different ways to print and format the exception and traceback:

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)

The output for the example would look similar to this:

*** 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

The following example shows the different ways to print and format the stack:

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

This last example demonstrates the final few formatting functions:

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

29.9. traceback — 打印或检索堆栈回溯 ¶

29.9.1. TracebackException 对象 ¶

29.9.2. StackSummary 对象 ¶

29.9.3. FrameSummary 对象 ¶

29.9.4. 回溯范例 ¶

内容表

上一话题

下一话题

本页

29.9. `traceback` — 打印或检索堆栈回溯 ¶

29.9.1. `TracebackException` 对象 ¶

29.9.2. `StackSummary` 对象 ¶

29.9.3. `FrameSummary` 对象 ¶