This module provides a standard interface to extract, format and print stacktraces of Python programs. It exactly mimics the behavior of the Pythoninterpreter when it prints a stack trace. This is useful when you want to printstack traces under program control, such as in a “wrapper” around theinterpreter.
The module uses traceback objects — this is the object type that is stored inthesys.last_traceback variable and returned as the third item fromsys.exc_info().
The module defines the following functions:
Print up tolimit stack trace entries fromtraceback. Iflimit is omittedorNone, all entries are printed. Iffile is omitted orNone, theoutput goes tosys.stderr; otherwise it should be an open file or file-likeobject to receive the output.
Print exception information and up tolimit stack trace entries fromtraceback tofile. This differs fromprint_tb() in the followingways:
Ifchain is true (the default), then chained exceptions (the__cause__ or__context__ attributes of the exception) will beprinted as well, like the interpreter itself does when printing an unhandledexception.
This is a shorthand forprint_exception(*sys.exc_info()).
This is a shorthand forprint_exception(sys.last_type,sys.last_value,sys.last_traceback,limit,file). In general it will work only afteran exception has reached an interactive prompt (seesys.last_type).
This function prints a stack trace from its invocation point. The optionalfargument can be used to specify an alternate stack frame to start. The optionallimit andfile arguments have the same meaning as forprint_exception().
Return a list of up tolimit “pre-processed” stack trace entries extractedfrom the traceback objecttraceback. It is useful for alternate formatting ofstack traces. Iflimit is omitted orNone, all entries are extracted. A“pre-processed” stack trace entry is a quadruple (filename,line number,function name,text) representing the information that is usually printedfor a stack trace. Thetext is a string with leading and trailing whitespacestripped; if the source is not available it isNone.
Extract the raw traceback from the current stack frame. The return value hasthe same format as forextract_tb(). The optionalf andlimitarguments have the same meaning as forprint_stack().
Given a list of tuples as returned byextract_tb() orextract_stack(), return a list of strings ready for printing. Each stringin the resulting list corresponds to the item with the same index in theargument list. Each string ends in a newline; the strings may contain internalnewlines as well, for those items whose source text line is notNone.
Format the exception part of a traceback. The arguments are the exception typeand value such as given bysys.last_type andsys.last_value. The returnvalue is a list of strings, each ending in a newline. Normally, the listcontains a single string; however, forSyntaxError exceptions, itcontains several lines that (when printed) display detailed information aboutwhere the syntax error occurred. The message indicating which exceptionoccurred is the always last string in the list.
Format a stack trace and the exception information. The arguments have thesame meaning as the corresponding arguments toprint_exception(). Thereturn value is a list of strings, each ending in a newline and some containinginternal newlines. When these lines are concatenated and printed, exactly thesame text is printed as doesprint_exception().
This is likeprint_exc(limit) but returns a string instead of printing to afile.
A shorthand forformat_list(extract_tb(tb,limit)).
A shorthand forformat_list(extract_stack(f,limit)).
This simple example implements a basic read-eval-print loop, similar to (butless useful than) the standard Python interactive interpreter loop. For a morecomplete implementation of the interpreter loop, refer to thecodemodule.
importsys,tracebackdefrun_user_code(envdir):source=input(">>> ")try:exec(source,envdir)except:print("Exception in user code:")print("-"*60)traceback.print_exc(file=sys.stdout)print("-"*60)envdir={}whileTrue:run_user_code(envdir)
The following example demonstrates the different ways to print and format theexception and traceback:
importsys,tracebackdeflumberjack():bright_side_of_death()defbright_side_of_death():returntuple()[0]try:lumberjack()exceptIndexError: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)
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:[('<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: 10The following example shows the different ways to print and format the stack:
>>>importtraceback>>>defanother_function():...lumberstack()...>>>deflumberstack():...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:
>>>importtraceback>>>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']
28.10.__future__ — Future statement definitions
Enter search terms or a module, class or function name.