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älpklasserStackSummary
ochFrameSummary
. 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 ärNone
, skrivs alla poster ut. Om file utelämnas eller ärNone
, går utdata tillsys.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 medsys.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 utTraceback (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 (sesys.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 ärNone
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örprint_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örprint_tb()
. En ”förbehandlad” stackspårningspost är ettFrameSummary
-objekt som innehåller attributenfilename
,lineno
,name
ochline
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örprint_stack()
.
- traceback.print_list(extracted_list, file=None)¶
Skriver ut listan med tupler som returneras av
extract_tb()
ellerextract_stack()
som ett formaterat stackspår till den angivna filen. Om file ärNone
skrivs utdata tillsys.stderr
.
- traceback.format_list(extracted_list)¶
Ger en lista med tupler eller
FrameSummary
-objekt som returneras avextract_tb()
ellerextract_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 ärNone
.
- 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örSyntaxError
-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 undantagetsnotes
.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 avBaseExceptionGroup
, 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 iprint_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 ärNone
används den aktuella stacken. Denna hjälp används medStackSummary.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 medStackSummary.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
:sformat()
-metod i klassens attribut. I synnerhet beräknas fältet__context__
endast om__cause__
ärNone
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.
- __context__¶
En
TracebackException
av den ursprungliga__context__
.
- exceptions¶
Om
self
representerar enExceptionGroup
, innehåller detta fält en lista avTracebackException
-instanser som representerar de nästlade undantagen. Annars är detNone
.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, ellerNone
om undantaget inte har några anteckningar. Om det inte ärNone
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 (standardsys.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örSyntaxError
-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 avBaseExceptionGroup
, 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 avwalk_stack()
ellerwalk_tb()
).Om limit anges kommer endast så många ramar att hämtas från frame_gen. Om lookup_lines är
False
, kommer de returneradeFrameSummary
-objekten inte att ha läst in sina rader ännu, vilket gör kostnaden för att skapaStackSummary
billigare (vilket kan vara värdefullt om det kanske inte faktiskt formateras). Om capture_locals ärTrue
fångas de lokala variablerna i varjeFrameSummary
som objektrepresentationer.Ändrad i version 3.12: Undantag från
repr()
på en lokal variabel (när capture_locals ärTrue
) sprids inte längre till den som anropar.
- classmethod from_list(a_list)¶
Konstruerar ett
StackSummary
-objekt från en medföljande lista avFrameSummary
-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 medStackSummary.format()
. Om den returnerarNone
, 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änFrameSummary
harline
attributet åtkomligt (vilket också händer när den kastas till entuple
).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
tilllineno
.
- 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