traceback — Skriv ut eller hämta en stack traceback

Källkod: Lib/traceback.py


Denna modul tillhandahåller ett standardgränssnitt för att extrahera, formatera och skriva ut stackspår från Python-program. Det är mer flexibelt än tolkens standardvisning av spårning, och gör det därför möjligt att konfigurera vissa aspekter av utdata. Slutligen innehåller den ett verktyg för att fånga tillräckligt med information om ett undantag för att skriva ut det senare, utan att behöva spara en referens till det faktiska undantaget. Eftersom undantag kan vara roten till stora objektgrafer kan detta verktyg förbättra minneshanteringen avsevärt.

Modulen använder traceback-objekt — dessa är objekt av typen types.TracebackType, som tilldelas fältet __traceback__ i BaseException-instanser.

Se även

Modul faulthandler

Används för att dumpa Python-spårningar explicit, vid ett fel, efter en timeout eller vid en användarsignal.

Modul pdb

Interaktiv källkodsfelsökare för Python-program.

Modulens API kan delas in i två delar:

  • Funktioner på modulnivå som erbjuder grundläggande funktionalitet och som är användbara för interaktiv inspektion av undantag och spårningar.

  • klassen TracebackException och dess hjälpklasser StackSummary och FrameSummary. Dessa ger både större flexibilitet i den utdata som genereras och möjlighet att lagra den information som behövs för senare formatering utan att hålla referenser till faktiska undantag och spårningsobjekt.

Tillagd i version 3.13: Utdata är färgade som standard och kan kontrolleras med hjälp av miljövariabler.

Funktioner på modulnivå

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

Skriv ut upp till limit stacktrace-poster från traceback object tb (med början från anroparens frame) om limit är positivt. Annars skrivs de senaste abs(limit)-posterna ut. Om limit utelämnas eller är None, skrivs alla poster ut. Om file utelämnas eller är None, går utdata till sys.stderr; annars ska det vara en öppen fil eller file-like object som tar emot utdata.

Anteckning

Betydelsen av parametern limit är annorlunda än betydelsen av sys.tracebacklimit. Ett negativt limit-värde motsvarar ett positivt värde på sys.tracebacklimit, medan beteendet hos ett positivt limit-värde inte kan uppnås med sys.tracebacklimit.

Ändrad i version 3.5: Stöd för negativ limit har lagts till.

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

Skriver ut undantagsinformation och stackspårningsposter från traceback object tb till file. Detta skiljer sig från print_tb() på följande sätt:

  • om tb inte är None, skrivs en rubrik ut Traceback (senaste anropet senast):

  • den skriver ut undantagstypen och värdet efter stackspårningen

  • om typ(värde) är SyntaxError och värde har rätt format, skrivs den rad ut där syntaxfelet inträffade med en caret som anger felets ungefärliga position.

Sedan Python 3.10, istället för att skicka value och tb, kan ett exception-objekt skickas som det första argumentet. Om value och tb anges ignoreras det första argumentet för att ge bakåtkompatibilitet.

Det valfria argumentet limit har samma betydelse som för print_tb(). Om chain är true (standard) kommer även kedjade undantag (attributen __cause__ eller __context__ för undantaget) att skrivas ut, precis som tolken själv gör när den skriver ut ett ohanterat undantag.

Ändrad i version 3.5: Argumentet etype ignoreras och härleds från typen av value.

Ändrad i version 3.10: Parametern etype har bytt namn till exc och är nu endast positionell.

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

Detta är en förkortning av print_exception(sys.exception(), limit=limit, file=file, chain=chain).

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

Detta är en förkortning av print_exception(sys.last_exc, limit=limit, file=file, chain=chain). I allmänhet fungerar det bara efter att ett undantag har nått en interaktiv prompt (se sys.last_exc).

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

Skriv ut upp till limit stacktrace-poster (med början från anropspunkten) om limit är positivt. Annars skrivs de senaste abs(limit)-posterna ut. Om limit utelämnas eller är None skrivs alla poster ut. Det valfria argumentet f kan användas för att ange en alternativ stackruta att börja med. Det valfria argumentet file har samma betydelse som för print_tb().

Ändrad i version 3.5: Stöd för negativ limit har lagts till.

traceback.extract_tb(tb, limit=None)

Returnerar ett StackSummary-objekt som representerar en lista med ”förbehandlade” stackspårningsposter som extraherats från traceback-objektet tb. Det är användbart för alternativ formatering av stackspårningar. Det valfria argumentet limit har samma betydelse som för print_tb(). En ”förbehandlad” stackspårningspost är ett FrameSummary-objekt som innehåller attributen filename, lineno, name och line som representerar den information som vanligtvis skrivs ut för en stackspårning.

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

Extraherar den råa tracebacken från den aktuella stack frame. Returvärdet har samma format som för extract_tb(). De valfria argumenten f och limit har samma betydelse som för print_stack().

traceback.print_list(extracted_list, file=None)

Skriver ut listan med tupler som returneras av extract_tb() eller extract_stack() som ett formaterat stackspår till den angivna filen. Om file är None skrivs utdata till sys.stderr.

traceback.format_list(extracted_list)

Ger en lista med tupler eller FrameSummary-objekt som returneras av extract_tb() eller extract_stack(), returnerar en lista med strängar redo för utskrift. Varje sträng i den resulterande listan motsvarar objektet med samma index i argumentlistan. Varje sträng slutar med en ny rad; strängarna kan även innehålla interna nya rader för de objekt vars källtextrad inte är None.

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

Formatera undantagsdelen av en spårning med hjälp av ett undantagsvärde som anges av sys.last_value. Returvärdet är en lista med strängar som var och en slutar med en ny rad. Listan innehåller undantagets meddelande, som normalt är en enda sträng, men för SyntaxError-undantag innehåller den flera rader som (när de skrivs ut) visar detaljerad information om var syntaxfelet inträffade. Efter meddelandet innehåller listan undantagets notes.

Sedan Python 3.10 kan ett exception-objekt skickas som första argument istället för value. Om value anges ignoreras det första argumentet för att ge bakåtkompatibilitet.

När show_group är True, och undantaget är en instans av BaseExceptionGroup, inkluderas även de nästlade undantagen, rekursivt, med indragning i förhållande till deras nästlingsdjup.

Ändrad i version 3.10: Parametern etype har bytt namn till exc och är nu endast positionell.

Ändrad i version 3.11: Den returnerade listan innehåller nu alla notes som är kopplade till undantaget.

Ändrad i version 3.13: parametern show_group har lagts till.

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

Formaterar en stackspårning och information om undantaget. Argumenten har samma betydelse som motsvarande argument i print_exception(). Returvärdet är en lista med strängar som var och en slutar med en ny rad och vissa innehåller interna nya rader. När dessa rader sammanfogas och skrivs ut, skrivs exakt samma text ut som i print_exception().

Ändrad i version 3.5: Argumentet etype ignoreras och härleds från typen av value.

Ändrad i version 3.10: Den här funktionens beteende och signatur har ändrats för att matcha print_exception().

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

Detta är som print_exc(limit) men returnerar en sträng istället för att skriva ut till en fil.

traceback.format_tb(tb, limit=None)

En förkortning för format_list(extract_tb(tb, limit)).

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

En förkortning för format_list(extract_stack(f, limit)).

traceback.clear_frames(tb)

Rensar de lokala variablerna för alla stackramar i en traceback tb genom att anropa metoden clear() för varje frame-objekt.

Tillagd i version 3.4.

traceback.walk_stack(f)

Går igenom en stack enligt f.f_back från den angivna ramen, vilket ger ram- och radnummer för varje ram. Om f är None används den aktuella stacken. Denna hjälp används med StackSummary.extract().

Tillagd i version 3.5.

Ändrad i version 3.14: Denna funktion returnerade tidigare en generator som skulle gå igenom stacken när den först itererades över. Den generator som returneras nu är stackens tillstånd när walk_stack anropas.

traceback.walk_tb(tb)

Går igenom en spårning enligt tb_next och ger bildrutan och radnumret för varje bildruta. Detta hjälpmedel används med StackSummary.extract().

Tillagd i version 3.5.

TracebackException-objekt

Tillagd i version 3.5.

TracebackException-objekt skapas från faktiska undantag för att fånga data för senare utskrift. De erbjuder en mer lättviktig metod för att lagra denna information genom att undvika att hålla referenser till traceback och frame objekt. Dessutom ger de fler alternativ för att konfigurera utdata jämfört med de funktioner på modulnivå som beskrivs ovan.

class traceback.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)

Fånga ett undantag för senare rendering. Betydelsen av limit, lookup_lines och capture_locals är densamma som för klassen StackSummary.

Om compact är true, sparas endast data som krävs av TracebackException:s format()-metod i klassens attribut. I synnerhet beräknas fältet __context__ endast om __cause__ är None och __suppress_context__ är false.

Observera att när lokala funktioner fångas upp visas de också i traceback.

max_group_width och max_group_depth styr formateringen av undantagsgrupper (se BaseExceptionGroup). Djupet avser gruppens nestningsnivå och bredden avser storleken på en enskild undantagsgrupps undantagsarray. Den formaterade utdata trunkeras när någon av gränserna överskrids.

Ändrad i version 3.10: Parametern kompakt har lagts till.

Ändrad i version 3.11: Parametrarna max_group_width och max_group_depth har lagts till.

__cause__

En TracebackException av den ursprungliga __cause__.

__context__

En TracebackException av den ursprungliga __context__.

exceptions

Om self representerar en ExceptionGroup, innehåller detta fält en lista av TracebackException-instanser som representerar de nästlade undantagen. Annars är det None.

Tillagd i version 3.11.

__suppress_context__

Värdet __suppress_context__ från det ursprungliga undantaget.

__notes__

Värdet __notes__ från det ursprungliga undantaget, eller None om undantaget inte har några anteckningar. Om det inte är None formateras det i tracebacken efter undantagssträngen.

Tillagd i version 3.11.

stack

En StackSummary som representerar spårningen.

exc_type

Klassen för den ursprungliga spårningen.

Föråldrad sedan version 3.13.

exc_type_str

Strängvisning av klassen för det ursprungliga undantaget.

Tillagd i version 3.13.

filename

För syntaxfel - filnamnet där felet uppstod.

lineno

För syntaxfel - radnumret där felet uppstod.

end_lineno

För syntaxfel - numret på slutraden där felet inträffade. Kan vara None om det inte finns.

Tillagd i version 3.10.

text

För syntaxfel - den text där felet inträffade.

offset

För syntaxfel - den offset i texten där felet uppstod.

end_offset

För syntaxfel - slutoffset i texten där felet uppstod. Kan vara None om det inte finns.

Tillagd i version 3.10.

msg

För syntaxfel - kompilatorns felmeddelande.

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

Fånga ett undantag för senare rendering. limit, lookup_lines och capture_locals är som för klassen StackSummary.

Observera att när lokala funktioner fångas upp visas de också i traceback.

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

Skriv ut undantagsinformationen som returneras av format() till fil (standard sys.stderr).

Tillagd i version 3.11.

format(*, chain=True)

Formatera undantaget.

Om chain inte är True, kommer __cause__ och __context__ inte att formateras.

Returvärdet är en generator av strängar, var och en slutar med en ny rad och vissa innehåller interna nya rader. print_exception() är ett omslag runt denna metod som bara skriver ut raderna till en fil.

format_exception_only(*, show_group=False)

Formatera undantagsdelen av tracebacken.

Returvärdet är en generator av strängar som var och en slutar med en ny rad.

När show_group är False, avger generatorn undantagets meddelande följt av dess anteckningar (om det har några). Undantagsmeddelandet är normalt en enda sträng, men för SyntaxError-undantag består det av flera rader som (när de skrivs ut) visar detaljerad information om var syntaxfelet uppstod.

När show_group är True, och undantaget är en instans av BaseExceptionGroup, inkluderas även de nästlade undantagen, rekursivt, med indragning i förhållande till deras nästlingsdjup.

Ändrad i version 3.11: Undantagets notes inkluderas nu i utdata.

Ändrad i version 3.13: Parametern show_group har lagts till.

StackSummary Objekt

Tillagd i version 3.5.

StackSummary-objekt representerar en anropsstack som är redo för formatering.

class traceback.StackSummary
classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)

Konstruera ett StackSummary-objekt från en ramgenerator (t.ex. den som returneras av walk_stack() eller walk_tb()).

Om limit anges kommer endast så många ramar att hämtas från frame_gen. Om lookup_lines är False, kommer de returnerade FrameSummary-objekten inte att ha läst in sina rader ännu, vilket gör kostnaden för att skapa StackSummary billigare (vilket kan vara värdefullt om det kanske inte faktiskt formateras). Om capture_locals är True fångas de lokala variablerna i varje FrameSummary som objektrepresentationer.

Ändrad i version 3.12: Undantag från repr() på en lokal variabel (när capture_locals är True) sprids inte längre till den som anropar.

classmethod from_list(a_list)

Konstruerar ett StackSummary-objekt från en medföljande lista av FrameSummary-objekt eller en gammaldags lista av tuplar. Varje tupel bör vara en 4-tupel med filnamn, lineno, namn, linje som element.

format()

Returnerar en lista med strängar som är klara för utskrift. Varje sträng i den resulterande listan motsvarar en enda frame från stacken. Varje sträng slutar med en ny rad; strängarna kan även innehålla interna nya rader, för de objekt som har källtextrader.

För långa sekvenser med samma ram och linje visas de första repetitionerna, följt av en sammanfattande rad som anger det exakta antalet ytterligare repetitioner.

Ändrad i version 3.6: Långa sekvenser av upprepade bildrutor förkortas nu.

format_frame_summary(frame_summary)

Returnerar en sträng för utskrift av en av de frames som ingår i stacken. Denna metod anropas för varje FrameSummary-objekt som ska skrivas ut med StackSummary.format(). Om den returnerar None, utelämnas ramen från utskriften.

Tillagd i version 3.11.

FrameSummary Objekt

Tillagd i version 3.5.

Ett FrameSummary-objekt representerar en enda frame i en traceback.

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

Representerar en enda frame i traceback eller stack som formateras eller skrivs ut. Den kan eventuellt ha en strängad version av ramens lokala information inkluderad i sig. Om lookup_line är False, kommer källkoden inte att sökas upp förrän FrameSummary har line attributet åtkomligt (vilket också händer när den kastas till en tuple). line kan anges direkt, och förhindrar att linjesökningar sker överhuvudtaget. locals är en valfri lokal variabelmappning, och om den anges lagras variabelrepresentationerna i sammanfattningen för senare visning.

FrameSummary-instanser har följande attribut:

filename

Filnamnet på källkoden för den här ramen. Motsvarar åtkomst till f.f_code.co_filename på en frame object f.

lineno

Radnumret i källkoden för den här ramen.

name

Motsvarar åtkomst till f.f_code.co_name på en frame object f.

line

En sträng som representerar källkoden för den här ramen, med inledande och avslutande blanksteg borttagna. Om källan inte är tillgänglig är den None.

end_lineno

Det sista radnumret i källkoden för den här ramen. Som standard är det inställt på lineno och indexeringen börjar från 1.

Ändrad i version 3.13: Standardvärdet ändrades från None till lineno.

colno

Kolumnnumret för källkoden för den här ramen. Som standard är det None och indexeringen börjar från 0.

end_colno

Det sista kolumnnumret i källkoden för den här ramen. Som standard är det None och indexeringen börjar från 0.

Exempel på användning av funktioner på modulnivå

Detta enkla exempel implementerar en grundläggande read-eval-print-loop, som liknar (men är mindre användbar än) Pythons interaktiva interpreter-loop. För en mer komplett implementering av tolkslingan, se modulen 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)

Följande exempel visar de olika sätten att skriva ut och formatera undantag och spårning:

import sys, traceback

def lumberjack():
    bright_side_of_life()

def bright_side_of_life():
    return tuple()[0]

try:
    lumberjack()
except IndexError as exc:
    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)

Utdata för exemplet skulle se ut ungefär så här:

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

Följande exempel visar de olika sätten att skriva ut och formatera stacken:

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

I det sista exemplet visas de sista formateringsfunktionerna:

>>> 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(an_error)
['IndexError: tuple index out of range\n']

Exempel på användning av TracebackException

Med hjälpklassen har vi fler alternativ:

>>> import sys
>>> from traceback import TracebackException
>>>
>>> def lumberjack():
...     bright_side_of_life()
...
>>> def bright_side_of_life():
...     t = "bright", "side", "of", "life"
...     return t[5]
...
>>> try:
...     lumberjack()
... except IndexError as e:
...     exc = e
...
>>> try:
...     try:
...         lumberjack()
...     except:
...         1/0
... except Exception as e:
...     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>", line 6, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-1>", line 10, in bright_side_of_life
    return t[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>", line 6, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-1>", line 10, in bright_side_of_life
    return t[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>", line 4, in <module>
    lumberjack()
    ~~~~~~~~~~^^
  File "<python-input-8>", line 7, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-8>", line 11, in bright_side_of_life
    return t[5]
           ~^^^
IndexError: tuple index out of range

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<python-input-19>", line 6, 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>", line 6, in <module>
    1/0
    ~^~
ZeroDivisionError: division by zero