Module-Level Functions¶

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

Print up tolimit stack trace entries fromtraceback objecttb (startingfrom the caller’s frame) iflimit is positive. Otherwise, print the lastabs(limit) entries. Iflimit is omitted orNone, all entries areprinted. Iffile is omitted orNone, the output goes tosys.stderr; otherwise it should be an openfile orfile-like object toreceive the output.

Note

The meaning of thelimit parameter is different than the meaningofsys.tracebacklimit. A negativelimit value corresponds toa positive value ofsys.tracebacklimit, whereas the behaviour ofa positivelimit value cannot be achieved withsys.tracebacklimit.

Changed in version 3.5:Added negativelimit support.

traceback.print_exception(exc,/,[value,tb,]limit=None,file=None,chain=True)¶

Print exception information and stack trace entries fromtraceback objecttb tofile. This differs fromprint_tb() in the followingways:

• iftb is notNone, it prints a headerTraceback(mostrecentcalllast):

• it prints the exception type andvalue after the stack trace

• iftype(value) isSyntaxError andvalue has the appropriateformat, it prints the line where the syntax error occurred with a caretindicating the approximate position of the error.

Since Python 3.10, instead of passingvalue andtb, an exception objectcan be passed as the first argument. Ifvalue andtb are provided, thefirst argument is ignored in order to provide backwards compatibility.

The optionallimit argument has the same meaning as forprint_tb().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.

Changed in version 3.5:Theetype argument is ignored and inferred from the type ofvalue.

Changed in version 3.10:Theetype parameter has been renamed toexc and is nowpositional-only.

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

This is a shorthand forprint_exception(sys.exception(),limit=limit,file=file,chain=chain).

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

This is a shorthand forprint_exception(sys.last_exc,limit=limit,file=file,chain=chain). In general it will work only after an exception has reachedan interactive prompt (seesys.last_exc).

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

Print up tolimit stack trace entries (starting from the invocationpoint) iflimit is positive. Otherwise, print the lastabs(limit)entries. Iflimit is omitted orNone, all entries are printed.The optionalf argument can be used to specify an alternatestack frameto start. The optionalfile argument has the same meaning as forprint_tb().

Changed in version 3.5:Added negativelimit support.

traceback.extract_tb(tb,limit=None)¶

Return aStackSummary object representing a list of “pre-processed”stack trace entries extracted from thetraceback objecttb. It is usefulfor alternate formatting of stack traces. The optionallimit argument hasthe same meaning as forprint_tb(). A “pre-processed” stack traceentry is aFrameSummary object containing attributesfilename,lineno,name, andline representing theinformation that is usually printed for a stack trace.

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

Extract the raw traceback from the currentstack frame. The return value hasthe same format as forextract_tb(). The optionalf andlimitarguments have the same meaning as forprint_stack().

traceback.print_list(extracted_list,file=None)¶

Print the list of tuples as returned byextract_tb() orextract_stack() as a formatted stack trace to the given file.Iffile isNone, the output is written tosys.stderr.

traceback.format_list(extracted_list)¶

Given a list of tuples orFrameSummary objects as returned byextract_tb() orextract_stack(), return a list of strings readyfor printing. Each string in the resulting list corresponds to the item withthe same index in the argument list. Each string ends in a newline; thestrings may contain internal newlines as well, for those items whose sourcetext line is notNone.

traceback.format_exception_only(exc,/,[value,]*,show_group=False)¶

Format the exception part of a traceback using an exception value such asgiven bysys.last_value. The return value is a list of strings, eachending in a newline. The list contains the exception’s message, which isnormally a single string; however, forSyntaxError exceptions, itcontains several lines that (when printed) display detailed informationabout where the syntax error occurred. Following the message, the listcontains the exception’snotes.

Since Python 3.10, instead of passingvalue, an exception objectcan be passed as the first argument. Ifvalue is provided, the firstargument is ignored in order to provide backwards compatibility.

Whenshow_group isTrue, and the exception is an instance ofBaseExceptionGroup, the nested exceptions are included aswell, recursively, with indentation relative to their nesting depth.

Changed in version 3.10:Theetype parameter has been renamed toexc and is nowpositional-only.

Changed in version 3.11:The returned list now includes anynotes attached to the exception.

Changed in version 3.13:show_group parameter was added.

traceback.format_exception(exc,/,[value,tb,]limit=None,chain=True)¶

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 somecontaining internal newlines. When these lines are concatenated and printed,exactly the same text is printed as doesprint_exception().

Changed in version 3.5:Theetype argument is ignored and inferred from the type ofvalue.

Changed in version 3.10:This function’s behavior and signature were modified to matchprint_exception().

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

This is likeprint_exc(limit) but returns a string instead of printing toa file.

traceback.format_tb(tb,limit=None)¶

A shorthand forformat_list(extract_tb(tb,limit)).

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

A shorthand forformat_list(extract_stack(f,limit)).

traceback.clear_frames(tb)¶

Clears the local variables of all the stack frames in atracebacktbby calling theclear() method of eachframe object.

Added in version 3.4.

traceback.walk_stack(f)¶

Walk a stack followingf.f_back from the given frame,yielding the frameand line number for each frame. Iff isNone, the current stack isused. This helper is used withStackSummary.extract().

Added in version 3.5.

Changed in version 3.14:This function previously returned a generator that would walk the stackwhen first iterated over. The generator returned now is the state of thestack whenwalk_stack is called.

traceback.walk_tb(tb)¶

Walk a traceback followingtb_next yielding the frame andline numberfor each frame. This helper is used withStackSummary.extract().

Added in version 3.5.

TracebackException Objects¶

TracebackException objects are created from actual exceptions tocapture data for later printing. They offer a more lightweight method ofstoring this information by avoiding holding references totraceback andframe objects.In addition, they expose more options to configure the output compared tothe module-level functions described above.

classtraceback.TracebackException(exc_type,exc_value,exc_traceback,*,limit=None,lookup_lines=True,capture_locals=False,compact=False,max_group_width=15,max_group_depth=10)¶

Capture an exception for later rendering. The meaning oflimit,lookup_lines andcapture_locals are as for theStackSummaryclass.

Ifcompact is true, only data that is required byTracebackException’sformat() methodis saved in the class attributes. In particular, the__context__ field is calculated only if__cause__ isNone and__suppress_context__ is false.

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

max_group_width andmax_group_depth control the formatting of exceptiongroups (seeBaseExceptionGroup). The depth refers to the nestinglevel of the group, and the width refers to the size of a single exceptiongroup’s exceptions array. The formatted output is truncated when eitherlimit is exceeded.

Changed in version 3.10:Added thecompact parameter.

Changed in version 3.11:Added themax_group_width andmax_group_depth parameters.

__cause__¶

ATracebackException of the original__cause__.

__context__¶

ATracebackException of the original__context__.

exceptions¶

Ifself represents anExceptionGroup, this field holds a list ofTracebackException instances representing the nested exceptions.Otherwise it isNone.

Added in version 3.11.

__suppress_context__¶

The__suppress_context__ value from the originalexception.

__notes__¶

The__notes__ value from the original exception,orNoneif the exception does not have any notes. If it is notNoneis it formatted in the traceback after the exception string.

Added in version 3.11.

stack¶

AStackSummary representing the traceback.

exc_type¶

The class of the original traceback.

Deprecated since version 3.13.

exc_type_str¶

String display of the class of the original exception.

Added in version 3.13.

filename¶

For syntax errors - the file name where the error occurred.

lineno¶

For syntax errors - the line number where the error occurred.

end_lineno¶

For syntax errors - the end line number where the error occurred.Can beNone if not present.

Added in version 3.10.

text¶

For syntax errors - the text where the error occurred.

offset¶

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

end_offset¶

For syntax errors - the end offset into the text where the error occurred.Can beNone if not present.

Added in version 3.10.

msg¶

For syntax errors - the compiler error message.

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

Capture an exception for later rendering.limit,lookup_lines andcapture_locals are as for theStackSummary class.

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

print(*,file=None,chain=True)¶

Print tofile (defaultsys.stderr) the exception information returned byformat().

Added in version 3.11.

format(*,chain=True)¶

Format the exception.

Ifchain is notTrue,__cause__ and__context__will not be formatted.

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

format_exception_only(*,show_group=False)¶

Format the exception part of the traceback.

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

Whenshow_group isFalse, the generator emits the exception’smessage followed by its notes (if it has any). The exception messageis normally a single string; however, forSyntaxError exceptions,it consists of several lines that (when printed) display detailedinformation about where the syntax error occurred.

Whenshow_group isTrue, and the exception is an instance ofBaseExceptionGroup, the nested exceptions are included aswell, recursively, with indentation relative to their nesting depth.

Changed in version 3.11:The exception’snotes are nowincluded in the output.

Changed in version 3.13:Added theshow_group parameter.

StackSummary Objects¶

StackSummary objects represent a call stack ready for formatting.

classtraceback.StackSummary¶

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

Construct aStackSummary object from a frame generator (such asis returned bywalk_stack() orwalk_tb()).

Iflimit is supplied, only this many frames are taken fromframe_gen.Iflookup_lines isFalse, the returnedFrameSummaryobjects will not have read their lines in yet, making the cost ofcreating theStackSummary cheaper (which may be valuable if itmay not actually get formatted). Ifcapture_locals isTrue thelocal variables in eachFrameSummary are captured as objectrepresentations.

Changed in version 3.12:Exceptions raised fromrepr() on a local variable (whencapture_locals isTrue) are no longer propagated to the caller.

classmethodfrom_list(a_list)¶

Construct aStackSummary object from a supplied list ofFrameSummary objects or old-style list of tuples. Each tupleshould be a 4-tuple withfilename,lineno,name,line as theelements.

format()¶

Returns a list of strings ready for printing. Each string in theresulting list corresponds to a singleframe fromthe stack.Each string ends in a newline; the strings may contain internalnewlines as well, for those items with source text lines.

For long sequences of the same frame and line, the first fewrepetitions are shown, followed by a summary line stating the exactnumber of further repetitions.

Changed in version 3.6:Long sequences of repeated frames are now abbreviated.

format_frame_summary(frame_summary)¶

Returns a string for printing one of theframesinvolved in the stack.This method is called for eachFrameSummary object to beprinted byStackSummary.format(). If it returnsNone, theframe is omitted from the output.

Added in version 3.11.

FrameSummary Objects¶

AFrameSummary object represents a singleframein atraceback.

classtraceback.FrameSummary(filename,lineno,name,*,lookup_line=True,locals=None,line=None,end_lineno=None,colno=None,end_colno=None)¶

Represents a singleframe in thetraceback or stack that is being formattedor printed. It may optionally have a stringified version of the frame’slocals included in it. Iflookup_line isFalse, the source code is notlooked up until theFrameSummary has thelineattribute accessed (which also happens when casting it to atuple).line may be directly provided, and will prevent linelookups happening at all.locals is an optional local variablemapping, and if supplied the variable representations are stored in thesummary for later display.

FrameSummary instances have the following attributes:

filename¶

The filename of the source code for this frame. Equivalent to accessingf.f_code.co_filename on aframe objectf.

lineno¶

The line number of the source code for this frame.

name¶

Equivalent to accessingf.f_code.co_name onaframe objectf.

line¶

A string representing the source code for this frame, with leading andtrailing whitespace stripped.If the source is not available, it isNone.

end_lineno¶

The last line number of the source code for this frame.By default, it is set tolineno and indexation starts from 1.

Changed in version 3.13:The default value changed fromNone tolineno.

colno¶

The column number of the source code for this frame.By default, it isNone and indexation starts from 0.

end_colno¶

The last column number of the source code for this frame.By default, it isNone and indexation starts from 0.

Examples of Using the Module-Level Functions¶

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)exceptException: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_life()defbright_side_of_life():returntuple()[0]try:lumberjack()exceptIndexErrorasexc:print("*** print_tb:")traceback.print_tb(exc.__traceback__,limit=1,file=sys.stdout)print("*** print_exception:")traceback.print_exception(exc,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:")print(repr(traceback.format_exception(exc)))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_life()    ~~~~~~~~~~~~~~~~~~~^^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_life()    ~~~~~~~~~~~~~~~~~~~^^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 default[0]>", line 10, in <module>\n    lumberjack()\n    ~~~~~~~~~~^^\n', '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n    ~~~~~~~~~~~~~~~~~~~^^\n', '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\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_life>]*** format_tb:['  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n    ~~~~~~~~~~^^\n', '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n    ~~~~~~~~~~~~~~~~~~~^^\n', '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n']*** tb_lineno: 10

The 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>", line10, in<module>another_function()  File"<doctest>", line3, inanother_functionlumberstack()  File"<doctest>", line6, inlumberstacktraceback.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(an_error)['IndexError: tuple index out of range\n']

Examples of UsingTracebackException¶

With the helper class, we have more options:

>>>importsys>>>fromtracebackimportTracebackException>>>>>>deflumberjack():...bright_side_of_life()...>>>defbright_side_of_life():...t="bright","side","of","life"...returnt[5]...>>>try:...lumberjack()...exceptIndexErrorase:...exc=e...>>>try:...try:...lumberjack()...except:...1/0...exceptExceptionase:...chained_exc=e...>>># limit works as with the module-level functions>>>TracebackException.from_exception(exc,limit=-2).print()Traceback (most recent call last):  File"<python-input-1>", line6, inlumberjackbright_side_of_life()~~~~~~~~~~~~~~~~~~~^^  File"<python-input-1>", line10, inbright_side_of_lifereturnt[5]~^^^IndexError:tuple index out of range>>># capture_locals adds local variables in frames>>>TracebackException.from_exception(exc,limit=-2,capture_locals=True).print()Traceback (most recent call last):  File"<python-input-1>", line6, inlumberjackbright_side_of_life()~~~~~~~~~~~~~~~~~~~^^  File"<python-input-1>", line10, inbright_side_of_lifereturnt[5]~^^^t=("bright","side","of","life")IndexError:tuple index out of range>>># The *chain* kwarg to print() controls whether chained>>># exceptions are displayed>>>TracebackException.from_exception(chained_exc).print()Traceback (most recent call last):  File"<python-input-19>", line4, in<module>lumberjack()~~~~~~~~~~^^  File"<python-input-8>", line7, inlumberjackbright_side_of_life()~~~~~~~~~~~~~~~~~~~^^  File"<python-input-8>", line11, inbright_side_of_lifereturnt[5]~^^^IndexError:tuple index out of rangeDuring handling of the above exception, another exception occurred:Traceback (most recent call last):  File"<python-input-19>", line6, in<module>1/0~^~ZeroDivisionError:division by zero>>>TracebackException.from_exception(chained_exc).print(chain=False)Traceback (most recent call last):  File"<python-input-19>", line6, in<module>1/0~^~ZeroDivisionError:division by zero