trace — Trace or track Python statement execution

Source code: Lib/trace.py

Das Modul trace ermöglicht Ihnen die Verfolgung der Programmausführung, das Generieren von kommentierten Anweisungs-Abdeckungslisten, das Drucken von Aufrufer-/Aufgerufenen-Beziehungen und das Auflisten von während eines Programmlaufs ausgeführten Funktionen. Es kann in einem anderen Programm oder über die Befehlszeile verwendet werden.

Siehe auch

Coverage.py

Ein beliebtes Drittanbieter-Abdeckungstool, das HTML-Ausgaben zusammen mit erweiterten Funktionen wie Branch-Coverage bietet.

Befehlszeilenverwendung

Das Modul trace kann über die Befehlszeile aufgerufen werden. Es kann so einfach sein wie

python -m trace --count -C . somefile.py ...

Das obige Beispiel führt somefile.py aus und generiert kommentierte Listen aller während der Ausführung importierten Python-Module im aktuellen Verzeichnis.

--help

Hilfetext anzeigen und beenden.

--version

Versionsnummer des Moduls anzeigen und beenden.

Hinzugefügt in Version 3.8: Option --module hinzugefügt, die die Ausführung eines ausführbaren Moduls ermöglicht.

Hauptoptionen

Beim Aufruf von trace muss mindestens eine der folgenden Optionen angegeben werden. Die Option --listfuncs ist gegenseitig ausschließend mit den Optionen --trace und --count. Wenn --listfuncs angegeben ist, werden weder --count noch --trace akzeptiert und umgekehrt.

-c, --count

Erzeugt nach Abschluss des Programms eine Reihe von kommentierten Listen, die zeigen, wie oft jede Anweisung ausgeführt wurde. Siehe auch --coverdir, --file und --no-report unten.

-t, --trace

Zeigt Zeilen an, wenn sie ausgeführt werden.

-l, --listfuncs

Zeigt die vom Programm aufgerufenen Funktionen an.

-r, --report

Erzeugt eine kommentierte Liste aus einem früheren Programmlauf, der die Optionen --count und --file verwendet hat. Dies führt keinen Code aus.

-T, --trackcalls

Zeigt die Aufruferbeziehungen an, die durch die Ausführung des Programms aufgedeckt wurden.

Modifikatoren

-f, --file=<file>

Name einer Datei, über die Zählungen aus mehreren Tracing-Läufen akkumuliert werden sollen. Sollte mit der Option --count verwendet werden.

-C, --coverdir=<dir>

Verzeichnis, in das die Berichtsdateien geschrieben werden. Der Abdeckungsbericht für package.module wird in die Datei dir/package/module.cover geschrieben.

-m, --missing

Beim Generieren von kommentierten Listen werden nicht ausgeführte Zeilen mit >>>>>> markiert.

-s, --summary

Bei Verwendung von --count oder --report wird eine kurze Zusammenfassung für jede verarbeitete Datei auf stdout geschrieben.

-R, --no-report

Keine kommentierten Listen generieren. Dies ist nützlich, wenn Sie mehrere Läufe mit --count durchführen und am Ende eine einzelne kommentierte Liste erstellen möchten.

-g, --timing

Jede Zeile mit der seit Programmstart vergangenen Zeit präfixieren. Wird nur während des Tracings verwendet.

Filter

Diese Optionen können mehrmals wiederholt werden.

--ignore-module=<mod>

Ignoriere jedes der angegebenen Modulnamen und seine Untermodule (falls es sich um ein Paket handelt). Das Argument kann eine durch Kommas getrennte Liste von Namen sein.

--ignore-dir=<dir>

Ignoriere alle Module und Pakete im angegebenen Verzeichnis und seinen Unterverzeichnissen. Das Argument kann eine durch os.pathsep getrennte Liste von Verzeichnissen sein.

Programmatische Schnittstelle

class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

Erzeugt ein Objekt zur Verfolgung der Ausführung einer einzelnen Anweisung oder eines Ausdrucks. Alle Parameter sind optional. *count* aktiviert die Zählung von Zeilennummern. *trace* aktiviert die Verfolgung der Zeilenausführung. *countfuncs* aktiviert die Auflistung der während des Laufs aufgerufenen Funktionen. *countcallers* aktiviert die Nachverfolgung von Aufruferbeziehungen. *ignoremods* ist eine Liste von Modulen oder Paketen, die ignoriert werden sollen. *ignoredirs* ist eine Liste von Verzeichnissen, deren Module oder Pakete ignoriert werden sollen. *infile* ist der Name der Datei, aus der gespeicherte Zählungen gelesen werden sollen. *outfile* ist der Name der Datei, in die aktualisierte Zählungen geschrieben werden sollen. *timing* aktiviert die Anzeige eines Zeitstempels relativ zum Startzeitpunkt des Tracings.

run(cmd)

Führt den Befehl aus und sammelt Statistiken aus der Ausführung mit den aktuellen Tracing-Parametern. *cmd* muss ein String oder ein Code-Objekt sein, das für die Übergabe an exec() geeignet ist.

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

Führt den Befehl aus und sammelt Statistiken aus der Ausführung mit den aktuellen Tracing-Parametern in der definierten globalen und lokalen Umgebung. Wenn nicht definiert, standardmäßig *globals* und *locals* leere Wörterbücher.

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

Ruft *func* mit den angegebenen Argumenten unter der Kontrolle des Trace-Objekts mit den aktuellen Tracing-Parametern auf.

results()

Gibt ein CoverageResults-Objekt zurück, das die kumulierten Ergebnisse aller vorherigen Aufrufe von run, runctx und runfunc für die gegebene Trace-Instanz enthält. Setzt die akkumulierten Trace-Ergebnisse nicht zurück.

class trace.CoverageResults

Ein Container für Abdeckungsergebnisse, der von Trace.results() erstellt wird. Sollte nicht direkt vom Benutzer erstellt werden.

update(other)

Zusammenführen von Daten aus einem anderen CoverageResults-Objekt.

write_results(show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False)

Abdeckungsergebnisse schreiben. Setzen Sie *show_missing* auf True, um Zeilen anzuzeigen, die keine Treffer hatten. Setzen Sie *summary* auf True, um die Abdeckungszusammenfassung pro Modul in die Ausgabe aufzunehmen. *coverdir* gibt das Verzeichnis an, in das die Abdeckungsergebnisdateien ausgegeben werden. Wenn *None*, werden die Ergebnisse für jede Quelldatei in ihrem Verzeichnis platziert.

Wenn *ignore_missing_files* auf True gesetzt ist, werden Abdeckungszählungen für nicht mehr vorhandene Dateien stillschweigend ignoriert. Andernfalls löst eine fehlende Datei eine FileNotFoundError aus.

Geändert in Version 3.13: Parameter *ignore_missing_files* hinzugefügt.

Ein einfaches Beispiel, das die Verwendung der programmatischen Schnittstelle demonstriert

import sys
import trace

# create a Trace object, telling it what to ignore, and whether to
# do tracing or line-counting or both.
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# run the new command using the given tracer
tracer.run('main()')

# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")