bdb — Felsökningsramverk

Källkod: Lib/bdb.py

Modulen bdb hanterar grundläggande felsökningsfunktioner, som att ställa in brytpunkter eller hantera körning via felsökaren.

Följande undantag definieras:

exception bdb.BdbQuit

Exception som orsakas av Bdb-klassen för att avsluta felsökaren.

Modulen bdb definierar också två klasser:

class bdb.Breakpoint(self, file, line, temporary=False, cond=None, funcname=None)

I den här klassen implementeras temporära brytpunkter, ignoreringsräkningar, inaktivering och (åter)aktivering samt villkor.

Brytpunkter indexeras med nummer genom en lista som heter bpbynumber och med (file, line) -par genom bplist. Den förstnämnda pekar på en enda instans av klassen Breakpoint. Den senare pekar på en lista av sådana instanser eftersom det kan finnas mer än en brytpunkt per rad.

När du skapar en brytpunkt bör dess associerade filnamn vara i kanonisk form. Om en funcname definieras kommer en brytpunkt hit att räknas när den första raden i den funktionen exekveras. En conditional brytpunkt räknar alltid en hit.

Breakpoint-instanser har följande metoder:

deleteMe()

Ta bort brytpunkten från listan som är kopplad till en fil/rad. Om det är den sista brytpunkten i den positionen raderas även posten för filen/raden.

enable()

Markera brytpunkten som aktiverad.

disable()

Markera brytpunkten som inaktiverad.

bpformat()

Returnerar en sträng med all information om brytpunkten, snyggt formaterad:

  • Brytpunktsnummer.

  • Tillfällig status (del eller keep).

  • Fil/linjeposition.

  • Bristande skick.

  • Antal gånger att ignorera.

  • Antal gånger träffad.

Tillagd i version 3.2.

bpprint(out=None)

Skriv ut resultatet av bpformat() till filen out, eller om den är None, till standardutmatningen.

Breakpoint-instanser har följande attribut:

file

Filnamn för Breakpoint.

line

Radnummer för Breakpoint inom file.

temporary

True om en Breakpoint vid (fil, rad) är temporär.

cond

Villkor för utvärdering av en Breakpoint vid (fil, rad).

funcname

Funktionsnamn som definierar om en Breakpoint nås när funktionen startas.

enabled

True om Breakpoint är aktiverat.

bpbynumber

Numeriskt index för en enskild instans av en Breakpoint.

bplist

Ordbok med Breakpoint-instanser indexerade med (file, line) tuples.

ignore

Antal gånger som en Breakpoint ska ignoreras.

hits

Räknar antalet gånger en Breakpoint har träffats.

class bdb.Bdb(skip=None, backend='settrace')

Klassen Bdb fungerar som en generisk basklass för Pythons felsökare.

Denna klass tar hand om detaljerna i spårningsfunktionen; en härledd klass bör implementera användarinteraktion. Standardklassen för debugger (pdb.Pdb) är ett exempel.

Argumentet skip, om det anges, måste vara en iterabel av modulnamnsmönster i glob-stil. Felsökaren kommer inte att gå in i ramar som har sitt ursprung i en modul som matchar något av dessa mönster. Huruvida en ram anses ha sitt ursprung i en viss modul avgörs av __name__ i ramglobalerna.

Argumentet backend anger vilken backend som ska användas för Bdb. Det kan vara antingen 'settrace' eller 'monitoring'. 'settrace' använder sys.settrace() som har den bästa bakåtkompatibiliteten. 'monitoring' backend använder den nya sys.monitoring som introducerades i Python 3.12, vilket kan vara mycket mer effektivt eftersom det kan inaktivera oanvända händelser. Vi försöker behålla de exakta gränssnitten för båda backends, men det finns vissa skillnader. Felsökningsutvecklare uppmuntras att använda 'monitoring'-backend för att uppnå bättre prestanda.

Ändrad i version 3.1: Lagt till parametern skip.

Ändrad i version 3.14: Lagt till parametern backend.

Följande metoder i Bdb behöver normalt inte åsidosättas.

canonic(filename)

Returnerar kanonisk form av filnamn.

För riktiga filnamn är den kanoniska formen en operativsystemberoende, case-normaliserad absolut sökväg. Ett filnamn med vinkelparenteser, t.ex. "<stdin>" som genererats i interaktivt läge, returneras oförändrat.

start_trace(self)

Starta spårning. För 'settrace' backend, är denna metod likvärdig med sys.settrace(self.trace_dispatch)

Tillagd i version 3.14.

stop_trace(self)

Stoppar spårning. För 'settrace' backend, är denna metod likvärdig med sys.settrace(None)

Tillagd i version 3.14.

reset()

Ställ in attributen botframe, stopframe, returnframe och quitting med värden som är redo att börja felsöka.

trace_dispatch(frame, event, arg)

Denna funktion installeras som spårningsfunktion för felsökta ramar. Dess returvärde är den nya spårningsfunktionen (i de flesta fall, dvs. sig själv).

Standardimplementeringen avgör hur en ram ska skickas, beroende på vilken typ av händelse (som skickas som en sträng) som ska utföras. event kan vara något av följande:

  • "linje": En ny kodrad kommer att exekveras.

  • "anrop": En funktion är på väg att anropas eller ett annat kodblock anges.

  • "return": En funktion eller ett annat kodblock är på väg att returnera.

  • "undantag": Ett undantag har inträffat.

  • "c_call": En C-funktion är på väg att anropas.

  • "c_return": En C-funktion har returnerats.

  • "c_exception": En C-funktion har orsakat ett undantag.

För Python-händelserna anropas specialiserade funktioner (se nedan). För C-händelser vidtas inga åtgärder.

Parametern arg beror på den föregående händelsen.

Se dokumentationen för sys.settrace() för mer information om trace-funktionen. För mer information om kod- och ramobjekt, se Standardtypens hierarki.

dispatch_line(frame)

Om felsökaren ska stanna på den aktuella raden, anropa metoden user_line() (som bör åsidosättas i underklasser). Utlöser ett BdbQuit-undantag om flaggan quitting är inställd (vilket kan ställas in från user_line()). Returnera en referens till metoden trace_dispatch() för vidare spårning i det området.

dispatch_call(frame, arg)

Om debuggern ska stoppas vid detta funktionsanrop, anropa metoden user_call() (som bör åsidosättas i underklasser). Utlöser ett BdbQuit undantag om quitting flaggan är inställd (som kan ställas in från user_call()). Returnera en referens till metoden trace_dispatch() för vidare spårning i det området.

dispatch_return(frame, arg)

Om felsökaren ska stoppas vid denna funktionsretur, anropa metoden user_return() (som bör åsidosättas i underklasser). Utlöser ett BdbQuit undantag om quitting flaggan är inställd (som kan ställas in från user_return()). Returnerar en referens till metoden trace_dispatch() för vidare spårning i det området.

dispatch_exception(frame, arg)

Om debuggern ska stoppas vid detta undantag, anropas metoden user_exception() (som bör åsidosättas i underklasser). Utlöser ett BdbQuit-undantag om flaggan quitting är inställd (vilket kan ställas in från user_exception()). Returnerar en referens till metoden trace_dispatch() för vidare spårning i det området.

Normalt åsidosätter inte härledda klasser följande metoder, men de kan göra det om de vill omdefiniera definitionen av stopp och brytpunkter.

is_skipped_line(module_name)

Returnerar True om modul_namn matchar något skip-mönster.

stop_here(frame)

Returnerar True om frame ligger under startramen i stacken.

break_here(frame)

Returnerar True om det finns en effektiv brytpunkt för den här raden.

Kontrollera om det finns en linje- eller funktionsbrytpunkt och om den är i kraft. Ta bort tillfälliga brytpunkter baserat på information från effective().

break_anywhere(frame)

Returnerar True om det finns någon brytpunkt för frame:s filnamn.

Härledda klasser bör åsidosätta dessa metoder för att få kontroll över felsökningsfunktionen.

user_call(frame, argument_list)

Anropas från dispatch_call() om en paus kan stoppas inuti den anropade funktionen.

argument_list används inte längre och kommer alltid att vara None. Argumentet behålls för bakåtkompatibilitet.

user_line(frame)

Anropas från dispatch_line() när antingen stop_here() eller break_here() returnerar True.

user_return(frame, return_value)

Anropas från dispatch_return() när stop_here() returnerar True.

user_exception(frame, exc_info)

Anropas från dispatch_exception() när stop_here() returnerar True.

do_clear(arg)

Hantera hur en brytpunkt måste tas bort när den är tillfällig.

Denna metod måste implementeras av härledda klasser.

Härledda klasser och klienter kan anropa följande metoder för att påverka stepping-läget.

set_step()

Stoppa efter en rad kod.

set_next(frame)

Stoppa på nästa linje i eller under den angivna ramen.

set_return(frame)

Stanna när du återvänder från den givna ramen.

set_until(frame, lineno=None)

Stoppa när linjen med lineno större än den aktuella linjen nås eller när du återvänder från den aktuella ramen.

set_trace([frame])

Starta felsökning från frame. Om frame inte anges startar felsökningen från den anropande enhetens frame.

Ändrad i version 3.13: set_trace() kommer att gå in i felsökaren omedelbart, snarare än på nästa kodrad som ska exekveras.

set_continue()

Stoppa endast vid brytpunkter eller när du är klar. Om det inte finns några brytpunkter, ställ in systemets spårningsfunktion till ”Ingen”.

set_quit()

Sätt attributet quitting till True. Detta ger upphov till BdbQuit i nästa anrop till en av dispatch_*()-metoderna.

Härledda klasser och klienter kan anropa följande metoder för att manipulera brytpunkter. Dessa metoder returnerar en sträng som innehåller ett felmeddelande om något gått fel, eller None om allt är bra.

set_break(filename, lineno, temporary=False, cond=None, funcname=None)

Ställ in en ny brytpunkt. Om lineno-raden inte finns för det filnamn som anges som argument, returneras ett felmeddelande. filnamnet bör vara i kanonisk form, enligt beskrivningen i metoden canonic().

clear_break(filename, lineno)

Ta bort brytpunkterna i filnamn och lineno. Om inga har angetts returneras ett felmeddelande.

clear_bpbynumber(arg)

Ta bort den brytpunkt som har indexet arg i Breakpoint.bpbynumber. Om arg inte är numeriskt eller ligger utanför intervallet returneras ett felmeddelande.

clear_all_file_breaks(filename)

Ta bort alla brytpunkter i filnamn. Om inga har angetts returneras ett felmeddelande.

clear_all_breaks()

Ta bort alla befintliga brytpunkter. Om inga har angetts, returneras ett felmeddelande.

get_bpbynumber(arg)

Returnerar en brytpunkt som specificeras av det angivna talet. Om arg är en sträng kommer den att konverteras till ett tal. Om arg är en icke-numerisk sträng, om den angivna brytpunkten aldrig har existerat eller har tagits bort, kommer ett ValueError att visas.

Tillagd i version 3.2.

get_break(filename, lineno)

Returnerar True om det finns en brytpunkt för lineno i filnamn.

get_breaks(filename, lineno)

Returnerar alla brytpunkter för lineno i filnamn, eller en tom lista om inga har angetts.

get_file_breaks(filename)

Returnerar alla brytpunkter i filnamn, eller en tom lista om inga har angetts.

get_all_breaks()

Returnera alla brytpunkter som är inställda.

Härledda klasser och klienter kan anropa följande metoder för att inaktivera och starta om händelser för att uppnå bättre prestanda. Dessa metoder fungerar endast när du använder backend 'monitoring'.

disable_current_event()

Inaktiverar den aktuella händelsen tills nästa gång restart_events() anropas. Detta är användbart när felsökaren inte är intresserad av den aktuella raden.

Tillagd i version 3.14.

restart_events()

Starta om alla inaktiverade händelser. Denna funktion anropas automatiskt i dispatch_* -metoder efter att user_* -metoder har anropats. Om dispatch_* -metoderna inte överskrivs kommer de inaktiverade händelserna att startas om efter varje användarinteraktion.

Tillagd i version 3.14.

Härledda klasser och klienter kan anropa följande metoder för att få en datastruktur som representerar en stackspårning.

get_stack(f, t)

Returnera en lista med (frame, lineno)-tupler i en stackspårning och en storlek.

Den senast anropade bildrutan hamnar sist i listan. Storleken är antalet bildrutor under den bildruta där felsökaren startades.

format_stack_entry(frame_lineno, lprefix=': ')

Returnerar en sträng med information om en stackpost, som är en (frame, lineno)-tupel. Retursträngen innehåller:

  • Det kanoniska filnamnet som innehåller ramen.

  • Funktionsnamnet eller "<lambda>".

  • De ingående argumenten.

  • Returvärdet.

  • Kodraden (om den finns).

Följande två metoder kan anropas av klienter för att använda en debugger för att debugga en statement, angiven som en sträng.

run(cmd, globals=None, locals=None)

Felsök en sats som exekveras via funktionen exec(). globals är standard för __main__.__dict__, locals är standard för globals.

runeval(expr, globals=None, locals=None)

Felsök ett uttryck som exekverats via funktionen eval(). globals och locals har samma betydelse som i run().

runctx(cmd, globals, locals)

För bakåtkompatibilitet. Anropar metoden run().

runcall(func, /, *args, **kwds)

Felsök ett enstaka funktionsanrop och returnera dess resultat.

Slutligen definierar modulen följande funktioner:

bdb.checkfuncname(b, frame)

Returnerar True om vi ska bryta här, beroende på hur Breakpoint b ställdes in.

Om den ställdes in via radnummer kontrolleras om b.line är samma som den i frame. Om brytpunkten ställdes in via funktionsnamn, måste vi kontrollera att vi är i rätt frame (rätt funktion) och om vi är på dess första körbara rad.

bdb.effective(file, line, frame)

Returnerar (aktiv brytpunkt, ta bort temporär flagga) eller (Ingen, Ingen) som brytpunkt att agera på.

Den aktiva brytpunkten är den första posten i bplist för (file, line) (som måste finnas) som är enabled, för vilken checkfuncname() är true, och som varken har en falsk condition eller positiv ignore count. Flaggan, som betyder att en tillfällig brytpunkt ska tas bort, är False endast när cond inte kan utvärderas (i vilket fall ignore ignoreras).

Om det inte finns någon sådan post returneras (None, None).

bdb.set_trace()

Starta felsökning med en Bdb-instans från anroparens ram.