Tracing

Tracing generiert Ereignisse für Aufrufe, Rückgaben, Ausnahmen, ausgeführte Quellcodezeilen und unter bestimmten Umständen ausgeführte Anweisungen.

Nur Zeilenereignisse werden von diesem PEP abgedeckt.

Wenn Tracing aktiviert ist, werden Zeilenereignisse generiert, wenn

• Eine neue Zeile Quellcode erreicht wird.
• Ein Rücksprung auftritt, auch wenn er zur selben Zeile springt, wie es bei Listen-Komprehensionen vorkommen kann.

Zusätzlich werden Zeilenereignisse nie für Quellcodezeilen generiert, die nicht ausgeführt werden.

Was gilt für das Tracing als Code

Alle Ausdrücke und Teile von Ausdrücken gelten als ausführbarer Code.

Im Allgemeinen gelten alle Anweisungen auch als ausführbarer Code. Wenn eine Anweisung jedoch über mehrere Zeilen verteilt ist, müssen wir überlegen, welche Teile einer Anweisung als ausführbarer Code gelten.

Anweisungen bestehen aus Schlüsselwörtern und Ausdrücken. Nicht alle Schlüsselwörter haben eine direkte Laufzeitwirkung, daher gelten nicht alle Schlüsselwörter als ausführbarer Code. Zum Beispiel ist else ein notwendiger Teil einer if-Anweisung, aber es gibt keine Laufzeitwirkung im Zusammenhang mit einem else.

Für Tracing-Zwecke werden die folgenden Schlüsselwörter nicht als ausführbarer Code betrachtet

• del – Der zu löschende Ausdruck wird als ausführbarer Code behandelt.
• else – Keine Laufzeitwirkung
• finally – Keine Laufzeitwirkung
• global – Rein deklarativ
• nonlocal – Rein deklarativ

Alle anderen Schlüsselwörter gelten als ausführbarer Code.

Beispiel-Ereignissequenzen

In den folgenden Beispielen werden Ereignisse als „Name“, f_lineno-Paare aufgeführt.

Der Code

1.     global x
2.     x = a

generiert das folgende Ereignis

"line" 2

Der Code

1.     try:
2.        pass
3.     finally:
4.        pass

generiert die folgenden Ereignisse

"line" 1
"line" 2
"line" 4

Der Code

1.      for (
2.          x) in [1]:
3.          pass
4.      return

generiert die folgenden Ereignisse

"line" 2       # evaluate [1]
"line" 1       # for
"line" 2       # store to x
"line" 3       # pass
"line" 1       # for
"line" 4       # return
"return" 1

Das Attribut f_lineno

• Wenn ein Frame-Objekt erstellt wird, wird das Attribut f_lineno auf die Zeile gesetzt, in der die Funktion oder Klasse definiert ist; dies ist die Zeile, in der das Schlüsselwort def oder class erscheint. Für Module wird es auf Null gesetzt.
• Das Attribut f_lineno wird aktualisiert, um der Zeilennummer zu entsprechen, die gerade ausgeführt wird, auch wenn das Tracing deaktiviert ist und kein Ereignis generiert wird.

Die neue Methode co_lines() von Code-Objekten

Die Methode co_lines() gibt einen Iterator zurück, der Tupel von Werten liefert, die jeweils die Zeilennummer eines Bereichs von Bytecodes darstellen. Jedes Tupel besteht aus drei Werten

• start – Der Offset (inklusiv) des Beginns des Bytecode-Bereichs
• end – Der Offset (exklusiv) des Endes des Bytecode-Bereichs
• line – Die Zeilennummer oder None, wenn die Bytecodes im gegebenen Bereich keine Zeilennummer haben.

Die generierte Sequenz hat die folgenden Eigenschaften

• Der erste Bereich in der Sequenz hat start von 0
• Die Bereiche (start, end) sind nicht abnehmend und aufeinanderfolgend. Das heißt, für jedes Paar von Tupeln ist start des zweiten gleich end des ersten.
• Kein Bereich ist rückwärts, d.h. end >= start für alle Tripel.
• Der letzte Bereich in der Sequenz hat end gleich der Größe des Bytecodes.
• line ist entweder eine positive ganze Zahl oder None

Das Attribut co_linetable

Das Attribut co_linetable enthält die Zeilennummerinformationen. Das Format ist opak, nicht spezifiziert und kann ohne Vorankündigung geändert werden. Das Attribut ist nur öffentlich, um die Erstellung neuer Code-Objekte zu unterstützen.

Das Attribut co_lnotab

Historisch gesehen enthielt das Attribut co_lnotab eine Zuordnung von Bytecode-Offset zu Zeilennummer, unterstützt aber keine Bytecodes ohne Zeilennummer. Aus Kompatibilitätsgründen wird das co_lnotab-Bytes-Objekt bei Bedarf verzögert erstellt. Für Bereiche von Bytecodes ohne Zeilennummer wird die Zeilennummer des vorherigen Bytecode-Bereichs verwendet.

Werkzeuge, die die co_lnotab-Tabelle parsen, sollten so bald wie möglich zur neuen Methode co_lines() wechseln.

Beispiele für Code, bei dem sich die Sequenz der Trace-Ereignisse ändert

In den folgenden Beispielen werden Ereignisse als „Name“, f_lineno-Paare aufgeführt.

0.  def spam(a):
1.      if a:
2.          eggs()
3.      else:
4.          pass

"line" 1
"line" 2
"line" 4
"return" 4

"line" 1
"line" 2
"return" 2

0.  def bar():
1.      pass
2.      pass
3.      pass

"line" 3
"return" 3

"line" 1
"line" 2
"line" 3
"return" 3

C API

Der Zugriff auf das Attribut f_lineno von Frame-Objekten über C-API-Funktionen ist unverändert. f_lineno kann von PyFrame_GetLineNumber gelesen werden. f_lineno kann nur über PyObject_SetAttr und ähnliche Funktionen gesetzt werden.

Der direkte Zugriff auf f_lineno über die zugrundeliegende Datenstruktur ist verboten.

Prozess-externe Debugger und Profiler

Prozess-externe Werkzeuge wie py-spy [1] können die C-API nicht verwenden und müssen die Zeilennummerntabelle selbst parsen. Obwohl das Format der Zeilennummerntabelle ohne Vorankündigung geändert werden kann, wird es während einer Veröffentlichung nicht geändert, es sei denn, es ist für eine Fehlerkorrektur unbedingt erforderlich.

Um den Aufwand für die Implementierung dieser Werkzeuge zu reduzieren, werden die folgende C-Struktur und Hilfsfunktionen bereitgestellt. Beachten Sie, dass diese Funktionen nicht Teil der C-API sind und in jeden Code, der sie verwenden muss, eingebunden werden müssen.

typedef struct addressrange {
    int ar_start;
    int ar_end;
    int ar_line;
    struct _opaque opaque;
} PyCodeAddressRange;

void PyLineTable_InitAddressRange(char *linetable, Py_ssize_t length, int firstlineno, PyCodeAddressRange *range);
int PyLineTable_NextAddressRange(PyCodeAddressRange *range);
int PyLineTable_PreviousAddressRange(PyCodeAddressRange *range);

PyLineTable_InitAddressRange initialisiert die PyCodeAddressRange-Struktur aus der Zeilennummerntabelle und der ersten Zeilennummer.

PyLineTable_NextAddressRange bewegt den Bereich zum nächsten Eintrag und gibt einen Wert ungleich Null zurück, wenn er gültig ist.

PyLineTable_PreviousAddressRange bewegt den Bereich zum vorherigen Eintrag und gibt einen Wert ungleich Null zurück, wenn er gültig ist.

Obwohl diese Funktionen nicht Teil der C-API sind, werden sie von allen zukünftigen Versionen von CPython bereitgestellt. Die PyLineTable_-Funktionen rufen die C-API nicht auf und können daher sicher in jedes Werkzeug kopiert werden, das sie verwenden muss. Die PyCodeAddressRange-Struktur wird nicht geändert, aber die _opaque-Struktur ist nicht Teil der Spezifikation und kann sich ändern.

Zum Beispiel gibt der folgende Code alle Adressbereiche aus

void print_address_ranges(char *linetable, Py_ssize_t length, int firstlineno)
{
    PyCodeAddressRange range;
    PyLineTable_InitAddressRange(linetable, length, firstlineno, &range);
    while (PyLineTable_NextAddressRange(&range)) {
        printf("Bytecodes from %d (inclusive) to %d (exclusive) ",
               range.start, range.end);
        if (range.line < 0) {
            /* line < 0 means no line number */
            printf("have no line number\n");
        }
        else {
            printf("have line number %d\n", range.line);
        }
    }
}