bdb — Debugger-Framework

Quellcode: Lib/bdb.py

Das Modul bdb behandelt grundlegende Debugger-Funktionen, wie das Setzen von Haltepunkten oder die Verwaltung der Ausführung über den Debugger.

Die folgende Ausnahme wird definiert

exception bdb.BdbQuit

Ausnahme, die von der Klasse Bdb zum Beenden des Debuggers ausgelöst wird.

Das Modul bdb definiert auch zwei Klassen

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

Diese Klasse implementiert temporäre Haltepunkte, Ignorier-Zähler, Deaktivierung und (Wieder-)Aktivierung sowie Bedingungen.

Haltepunkte werden über eine Liste namens bpbynumber und über Tupel aus (Datei, Zeile) über bplist nach Nummern indiziert. Ersteres verweist auf eine einzelne Instanz der Klasse Breakpoint. Letzteres verweist auf eine Liste solcher Instanzen, da es mehr als einen Haltepunkt pro Zeile geben kann.

Beim Erstellen eines Haltepunkts sollte sein zugehöriger Dateiname im kanonischen Format vorliegen. Wenn ein Funktionsname definiert ist, wird ein Treffer des Haltepunkts gezählt, wenn die erste Zeile dieser Funktion ausgeführt wird. Ein bedingter Haltepunkt zählt immer einen Treffer.

Breakpoint-Instanzen haben die folgenden Methoden

deleteMe()

Löscht den Haltepunkt aus der Liste, die einer Datei/Zeile zugeordnet ist. Wenn es der letzte Haltepunkt an dieser Position ist, wird auch der Eintrag für Datei/Zeile gelöscht.

enable()

Markiert den Haltepunkt als aktiviert.

disable()

Markiert den Haltepunkt als deaktiviert.

bpformat()

Gibt eine schön formatierte Zeichenkette mit allen Informationen zum Haltepunkt zurück

  • Haltepunktnummer.

  • Temporärer Status (löschen oder beibehalten).

  • Datei/Zeilenposition.

  • Bedingung für den Haltepunkt.

  • Anzahl der zu ignorierenden Treffer.

  • Anzahl der Treffer.

Hinzugefügt in Version 3.2.

bpprint(out=None)

Gibt die Ausgabe von bpformat() in die Datei out aus, oder wenn diese None ist, auf die Standardausgabe.

Breakpoint-Instanzen haben die folgenden Attribute

file

Dateiname des Breakpoint.

line

Zeilennummer des Breakpoint innerhalb von file.

temporary

True, wenn ein Breakpoint an (Datei, Zeile) temporär ist.

cond

Bedingung für die Auswertung eines Breakpoint an (Datei, Zeile).

funcname

Funktionsname, der bestimmt, ob ein Breakpoint beim Eintritt in die Funktion ausgelöst wird.

enabled

True, wenn der Breakpoint aktiviert ist.

bpbynumber

Numerischer Index für eine einzelne Instanz eines Breakpoint.

bplist

Wörterbuch von Breakpoint-Instanzen, indiziert nach (Datei, Zeile) Tupeln.

ignore

Anzahl der zu ignorierenden Treffer eines Breakpoint.

hits

Anzahl der Treffer eines Breakpoint.

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

Die Klasse Bdb fungiert als generische Basisklasse für Python-Debugger.

Diese Klasse kümmert sich um die Details der Trace-Einrichtung; eine abgeleitete Klasse sollte die Benutzerinteraktion implementieren. Die Standard-Debuggerklasse (pdb.Pdb) ist ein Beispiel.

Das Argument skip muss, falls vorhanden, ein Iterable von Mustern für Modulnamen im Glob-Stil sein. Der Debugger tritt nicht in Frames ein, die aus einem Modul stammen, das einem dieser Muster entspricht. Ob ein Frame als aus einem bestimmten Modul stammend betrachtet wird, wird durch __name__ in den globalen Variablen des Frames bestimmt.

Das Argument backend gibt das zu verwendende Backend für Bdb an. Es kann entweder 'settrace' oder 'monitoring' sein. 'settrace' verwendet sys.settrace(), das die beste Rückwärtskompatibilität bietet. Das 'monitoring' Backend verwendet die neue sys.monitoring-Funktion, die in Python 3.12 eingeführt wurde und deutlich effizienter sein kann, da sie ungenutzte Ereignisse deaktivieren kann. Wir versuchen, die exakten Schnittstellen für beide Backends beizubehalten, aber es gibt einige Unterschiede. Debuggerentwickler werden ermutigt, das 'monitoring' Backend zu verwenden, um eine bessere Leistung zu erzielen.

Geändert in Version 3.1: Der Parameter skip wurde hinzugefügt.

Geändert in Version 3.14: Der Parameter backend wurde hinzugefügt.

Die folgenden Methoden von Bdb müssen normalerweise nicht überschrieben werden.

canonic(filename)

Gibt die kanonische Form von filename zurück.

Für echte Dateinamen ist die kanonische Form ein betriebssystemabhängiger, fall-normalisierter absoluter Pfad. Ein Dateiname mit spitzen Klammern, wie z.B. "<stdin>", der im interaktiven Modus generiert wird, wird unverändert zurückgegeben.

start_trace(self)

Startet das Tracing. Für das 'settrace' Backend ist diese Methode äquivalent zu sys.settrace(self.trace_dispatch).

Hinzugefügt in Version 3.14.

stop_trace(self)

Stoppt das Tracing. Für das 'settrace' Backend ist diese Methode äquivalent zu sys.settrace(None).

Hinzugefügt in Version 3.14.

reset()

Setzt die Attribute botframe, stopframe, returnframe und quitting auf Werte, die bereit sind, mit dem Debugging zu beginnen.

trace_dispatch(frame, event, arg)

Diese Funktion wird als Trace-Funktion für debuggte Frames installiert. Ihr Rückgabewert ist die neue Trace-Funktion (in den meisten Fällen ist das sie selbst).

Die Standardimplementierung entscheidet, wie ein Frame dispatcht wird, abhängig von der Art des Ereignisses (als Zeichenkette übergeben), das gerade ausgeführt werden soll. event kann einer der folgenden sein:

  • "line": Eine neue Codezeile wird ausgeführt.

  • "call": Eine Funktion wird aufgerufen oder ein anderer Codeblock betreten.

  • "return": Eine Funktion oder ein anderer Codeblock wird gerade beendet.

  • "exception": Eine Ausnahme ist aufgetreten.

  • "c_call": Eine C-Funktion wird aufgerufen.

  • "c_return": Eine C-Funktion wurde beendet.

  • "c_exception": Eine C-Funktion hat eine Ausnahme ausgelöst.

Für die Python-Ereignisse werden spezialisierte Funktionen (siehe unten) aufgerufen. Für die C-Ereignisse wird keine Aktion durchgeführt.

Der Parameter arg hängt vom vorherigen Ereignis ab.

Weitere Informationen zur Trace-Funktion finden Sie in der Dokumentation von sys.settrace(). Informationen zu Code- und Frame-Objekten finden Sie in Die Standard-Typenhierarchie.

dispatch_line(frame)

Wenn der Debugger bei der aktuellen Zeile stoppen soll, ruft er die Methode user_line() auf (die in abgeleiteten Klassen überschrieben werden sollte). Löst eine BdbQuit-Ausnahme aus, wenn das Flag quitting gesetzt ist (was von user_line() gesetzt werden kann). Gibt eine Referenz auf die Methode trace_dispatch() für weiteres Tracing in diesem Geltungsbereich zurück.

dispatch_call(frame, arg)

Wenn der Debugger bei diesem Funktionsaufruf stoppen soll, ruft er die Methode user_call() auf (die in abgeleiteten Klassen überschrieben werden sollte). Löst eine BdbQuit-Ausnahme aus, wenn das Flag quitting gesetzt ist (was von user_call() gesetzt werden kann). Gibt eine Referenz auf die Methode trace_dispatch() für weiteres Tracing in diesem Geltungsbereich zurück.

dispatch_return(frame, arg)

Wenn der Debugger bei dieser Rückkehr aus einer Funktion stoppen soll, ruft er die Methode user_return() auf (die in abgeleiteten Klassen überschrieben werden sollte). Löst eine BdbQuit-Ausnahme aus, wenn das Flag quitting gesetzt ist (was von user_return() gesetzt werden kann). Gibt eine Referenz auf die Methode trace_dispatch() für weiteres Tracing in diesem Geltungsbereich zurück.

dispatch_exception(frame, arg)

Wenn der Debugger bei dieser Ausnahme stoppen soll, ruft er die Methode user_exception() auf (die in abgeleiteten Klassen überschrieben werden sollte). Löst eine BdbQuit-Ausnahme aus, wenn das Flag quitting gesetzt ist (was von user_exception() gesetzt werden kann). Gibt eine Referenz auf die Methode trace_dispatch() für weiteres Tracing in diesem Geltungsbereich zurück.

Abgeleitete Klassen überschreiben die folgenden Methoden normalerweise nicht, können dies aber tun, wenn sie die Definition von Stopp- und Haltepunkten neu definieren möchten.

is_skipped_line(module_name)

Gibt True zurück, wenn module_name einem Skip-Muster entspricht.

stop_here(frame)

Gibt True zurück, wenn sich frame unterhalb des Start-Frames im Stack befindet.

break_here(frame)

Gibt True zurück, wenn für diese Zeile ein effektiver Haltepunkt existiert.

Prüft, ob ein Zeilen- oder Funktionshaltepunkt existiert und wirksam ist. Löscht temporäre Haltepunkte basierend auf Informationen von effective().

break_anywhere(frame)

Gibt True zurück, wenn für den Dateinamen von frame ein Haltepunkt existiert.

Abgeleitete Klassen sollten diese Methoden überschreiben, um die Steuerung des Debuggerbetriebs zu übernehmen.

user_call(frame, argument_list)

Wird von dispatch_call() aufgerufen, wenn ein Breakpoint innerhalb der aufgerufenen Funktion stoppen könnte.

argument_list wird nicht mehr verwendet und ist immer None. Das Argument wird aus Gründen der Abwärtskompatibilität beibehalten.

user_line(frame)

Wird von dispatch_line() aufgerufen, wenn entweder stop_here() oder break_here() True zurückgibt.

user_return(frame, return_value)

Wird von dispatch_return() aufgerufen, wenn stop_here() True zurückgibt.

user_exception(frame, exc_info)

Wird von dispatch_exception() aufgerufen, wenn stop_here() True zurückgibt.

do_clear(arg)

Behandelt, wie ein Haltepunkt entfernt werden muss, wenn er temporär ist.

Diese Methode muss von abgeleiteten Klassen implementiert werden.

Abgeleitete Klassen und Clients können die folgenden Methoden aufrufen, um den Schritt-Status zu beeinflussen.

set_step()

Stoppt nach einer Codezeile.

set_next(frame)

Stoppt bei der nächsten Zeile in oder unterhalb des gegebenen Frames.

set_return(frame)

Stoppt beim Rücksprung aus dem gegebenen Frame.

set_until(frame, lineno=None)

Stoppt, wenn die Zeile mit einer Nummer größer als die aktuelle erreicht wird, oder beim Rücksprung aus dem aktuellen Frame.

set_trace([frame])

Beginnt das Debugging ab dem Frame frame. Wenn frame nicht angegeben ist, beginnt das Debugging ab dem Frame des Aufrufers.

Geändert in Version 3.13: set_trace() tritt sofort in den Debugger ein, anstatt bei der nächsten auszuführenden Codezeile.

set_continue()

Stoppt nur bei Haltepunkten oder wenn das Programm beendet ist. Wenn keine Haltepunkte vorhanden sind, wird die System-Trace-Funktion auf None gesetzt.

set_quit()

Setzt das Attribut quitting auf True. Dies löst BdbQuit beim nächsten Aufruf einer der dispatch_*() Methoden aus.

Abgeleitete Klassen und Clients können die folgenden Methoden aufrufen, um Haltepunkte zu manipulieren. Diese Methoden geben eine Zeichenkette mit einer Fehlermeldung zurück, wenn etwas schief geht, oder None, wenn alles in Ordnung ist.

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

Setzt einen neuen Haltepunkt. Wenn die Zeile lineno für die als Argument übergebene Datei filename nicht existiert, wird eine Fehlermeldung zurückgegeben. Der Dateiname sollte im kanonischen Format vorliegen, wie in der Methode canonic() beschrieben.

clear_break(filename, lineno)

Löscht die Haltepunkte in filename und lineno. Wenn keine gesetzt waren, wird eine Fehlermeldung zurückgegeben.

clear_bpbynumber(arg)

Löscht den Haltepunkt mit dem Index arg in Breakpoint.bpbynumber. Wenn arg keine Zahl ist oder außerhalb des Bereichs liegt, wird eine Fehlermeldung zurückgegeben.

clear_all_file_breaks(filename)

Löscht alle Haltepunkte in filename. Wenn keine gesetzt waren, wird eine Fehlermeldung zurückgegeben.

clear_all_breaks()

Löscht alle vorhandenen Haltepunkte. Wenn keine gesetzt waren, wird eine Fehlermeldung zurückgegeben.

get_bpbynumber(arg)

Gibt einen Haltepunkt zurück, der durch die angegebene Nummer spezifiziert ist. Wenn arg eine Zeichenkette ist, wird sie in eine Zahl umgewandelt. Wenn arg eine nicht-numerische Zeichenkette ist, wenn der angegebene Haltepunkt nie existiert hat oder gelöscht wurde, wird ein ValueError ausgelöst.

Hinzugefügt in Version 3.2.

get_break(filename, lineno)

Gibt True zurück, wenn für lineno in filename ein Breakpoint existiert.

get_breaks(filename, lineno)

Gibt alle Breakpoints für lineno in filename zurück, oder eine leere Liste, wenn keine gesetzt sind.

get_file_breaks(filename)

Gibt alle Breakpoints in filename zurück, oder eine leere Liste, wenn keine gesetzt sind.

get_all_breaks()

Gibt alle gesetzten Breakpoints zurück.

Abgeleitete Klassen und Clients können die folgenden Methoden aufrufen, um Ereignisse zu deaktivieren und neu zu starten, um eine bessere Leistung zu erzielen. Diese Methoden funktionieren nur, wenn das Backend 'monitoring' verwendet wird.

disable_current_event()

Deaktiviert das aktuelle Ereignis, bis restart_events() das nächste Mal aufgerufen wird. Dies ist hilfreich, wenn der Debugger nicht an der aktuellen Zeile interessiert ist.

Hinzugefügt in Version 3.14.

restart_events()

Startet alle deaktivierten Ereignisse neu. Diese Funktion wird automatisch in den dispatch_* Methoden aufgerufen, nachdem die user_* Methoden aufgerufen wurden. Wenn die dispatch_* Methoden nicht überschrieben werden, werden die deaktivierten Ereignisse nach jeder Benutzerinteraktion neu gestartet.

Hinzugefügt in Version 3.14.

Abgeleitete Klassen und Clients können die folgenden Methoden aufrufen, um eine Datenstruktur zu erhalten, die einen Stacktrace repräsentiert.

get_stack(f, t)

Gibt eine Liste von (frame, lineno) Tupeln in einem Stacktrace und eine Größe zurück.

Der zuletzt aufgerufene Frame ist der letzte in der Liste. Die Größe ist die Anzahl der Frames unterhalb des Frames, in dem der Debugger aufgerufen wurde.

format_stack_entry(frame_lineno, lprefix=': ')

Gibt einen String mit Informationen zu einem Stack-Eintrag zurück, bei dem es sich um ein Tupel (frame, lineno) handelt. Der zurückgegebene String enthält

  • Den kanonischen Dateinamen, der den Frame enthält.

  • Den Funktionsnamen oder "<lambda>".

  • Die Eingabeargumente.

  • Der Rückgabewert.

  • Die Codezeile (falls vorhanden).

Die folgenden beiden Methoden können von Clients aufgerufen werden, um einen Debugger zu verwenden, um eine Anweisung zu debuggen, die als String übergeben wird.

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

Debuggt eine Anweisung, die über die Funktion exec() ausgeführt wird. globals ist standardmäßig __main__.__dict__, locals ist standardmäßig globals.

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

Debuggt einen Ausdruck, der über die Funktion eval() ausgeführt wird. globals und locals haben die gleiche Bedeutung wie in run().

runctx(cmd, globals, locals)

Zur Abwärtskompatibilität. Ruft die Methode run() auf.

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

Debuggt einen einzelnen Funktionsaufruf und gibt dessen Ergebnis zurück.

Schließlich definiert das Modul die folgenden Funktionen

bdb.checkfuncname(b, frame)

Gibt True zurück, wenn hier unterbrochen werden soll, abhängig davon, wie der Breakpoint b gesetzt wurde.

Wenn er über die Zeilennummer gesetzt wurde, wird geprüft, ob b.line mit der im frame übereinstimmt. Wenn der Breakpoint über den Funktionsnamen gesetzt wurde, muss geprüft werden, ob wir uns im richtigen frame (der richtigen Funktion) befinden und ob wir uns auf seiner ersten ausführbaren Zeile befinden.

bdb.effective(file, line, frame)

Gibt (aktiver Breakpoint, Löschflagge für temporären Breakpoint) oder (None, None) als zu bearbeitenden Breakpoint zurück.

Der aktive Breakpoint ist der erste Eintrag in bplist für das Tupel (file, line) (das existieren muss), der aktiviert ist, für den checkfuncname() wahr ist und der weder eine falsche Bedingung noch einen positiven Ignorierzähler aufweist. Die Flagge, die besagt, dass ein temporärer Breakpoint gelöscht werden soll, ist nur dann False, wenn die Bedingung nicht ausgewertet werden kann (in diesem Fall wird der Ignorierzähler ignoriert).

Wenn kein solcher Eintrag existiert, wird (None, None) zurückgegeben.

bdb.set_trace()

Startet das Debugging mit einer Bdb-Instanz aus dem Frame des Aufrufers.