Offset-Semantik

Diese Offsets werden vom Compiler aus den derzeit in allen AST-Knoten gespeicherten Offsets übernommen. Die Ausgabe der öffentlichen APIs (co_positions und PyCode_Addr2Location), die sich mit diesen Attributen befassen, verwendet 0-indizierte Offsets (genau wie die AST-Knoten), aber die zugrunde liegende Implementierung kann die tatsächlichen Daten in jeder Form darstellen, die sie für am effizientesten hält. Der Fehlercode bezüglich nicht verfügbarer Informationen ist None für die co_positions() API und -1 für die PyCode_Addr2Location API. Die Verfügbarkeit der Informationen hängt stark davon ab, ob die Offsets in den Bereich fallen, sowie von den Laufzeit-Flags der Interpreterkonfiguration.

Die AST-Knoten verwenden int-Typen, um diese Werte zu speichern. Die aktuelle Implementierung verwendet jedoch uint8_t-Typen als Implementierungsdetail, um den Speicherbedarf zu minimieren. Diese Entscheidung erlaubt Offsets von 0 bis 255, während Offsets größer als diese Werte als fehlend behandelt werden (was zu -1 in PyCode_Addr2Location und None in der co_positions() API führt).

Wie zuvor angegeben, sollte die zugrunde liegende Speicherung der Offsets als Implementierungsdetail betrachtet werden, da die öffentlichen APIs zum Abrufen dieser Werte entweder C int-Typen oder Python int-Objekte zurückgeben, was eine bessere Kompression/Kodierung in Zukunft ermöglicht, falls größere Bereiche unterstützt werden müssten. Diese PEP schlägt vor, mit dieser einfacheren Version zu beginnen und Verbesserungen für zukünftige Arbeiten aufzusparen.

Tracebacks anzeigen

Beim Anzeigen von Tracebacks wird der Standard-Exception-Hook modifiziert, um diese Informationen von den Code-Objekten abzurufen und sie zu verwenden, um eine Sequenz von Carets für jede angezeigte Zeile im Traceback anzuzeigen, falls die Informationen verfügbar sind. Zum Beispiel:

  File "test.py", line 6, in lel
    return 1 + foo(a,b,c=x['z']['x']['y']['z']['y'], d=e)
                         ~~~~~~~~~~~~~~~~^^^^^
TypeError: 'NoneType' object is not subscriptable

Beim Anzeigen von Tracebacks werden Instruktions-Offsets aus den Traceback-Objekten übernommen. Dadurch funktionieren Hervorhebungen von erneut ausgelösten Ausnahmen natürlich, ohne dass die neuen Informationen im Stack gespeichert werden müssen. Zum Beispiel für diesen Code:

def foo(x):
    1 + 1/0 + 2

def bar(x):
    try:
        1 + foo(x) + foo(x)
    except Exception as e:
        raise ValueError("oh no!") from e

bar(bar(bar(2)))

Der ausgegebene Traceback würde so aussehen:

Traceback (most recent call last):
  File "test.py", line 6, in bar
    1 + foo(x) + foo(x)
        ^^^^^^
  File "test.py", line 2, in foo
    1 + 1/0 + 2
        ~^~
ZeroDivisionError: division by zero

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "test.py", line 10, in <module>
    bar(bar(bar(2)))
            ^^^^^^
  File "test.py", line 8, in bar
    raise ValueError("oh no!") from e
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ValueError: oh no

Während dieser Code

def foo(x):
    1 + 1/0 + 2
def bar(x):
    try:
        1 + foo(x) + foo(x)
    except Exception:
        raise
bar(bar(bar(2)))

würde wie folgt angezeigt werden:

Traceback (most recent call last):
  File "test.py", line 10, in <module>
    bar(bar(bar(2)))
            ^^^^^^
  File "test.py", line 6, in bar
    1 + foo(x) + foo(x)
        ^^^^^^
  File "test.py", line 2, in foo
    1 + 1/0 + 2
        ~^~
ZeroDivisionError: division by zero

Unter Beibehaltung des aktuellen Verhaltens wird in Tracebacks nur eine einzige Zeile angezeigt. Für Anweisungen, die sich über mehrere Zeilen erstrecken (der End-Offset und der Start-Offset gehören zu unterschiedlichen Zeilen), muss die Endzeilennummer geprüft werden, um zu wissen, ob der End-Offset zur selben Zeile wie der Start-Offset gehört.

Opt-out-Mechanismus

Um einen Opt-out-Mechanismus für Benutzer anzubieten, die den Speicher- und Speicheraufwand berücksichtigen, und um Drittanbieter-Tools und andere Programme, die derzeit Tracebacks parsen, die Möglichkeit zu geben, sich anzupassen, werden die folgenden Methoden bereitgestellt, um diese Funktion zu deaktivieren:

• Eine neue Umgebungsvariable: PYTHONNODEBUGRANGES.
• Eine neue Kommandozeilenoption für den Entwicklermodus: python -Xno_debug_ranges.

Wenn eine dieser Methoden verwendet wird, wird der Python-Compiler die Code-Objekte **nicht** mit den neuen Informationen (stattdessen wird None verwendet) befüllen, und alle demarshallierten Code-Objekte, die die zusätzlichen Informationen enthalten, werden diese entfernt und durch None ersetzt. Zusätzlich wird die Traceback-Maschinerie die erweiterten Standortinformationen nicht anzeigen, selbst wenn die Informationen vorhanden waren. Diese Methode ermöglicht es Benutzern:

• Kleinere pyc-Dateien zu erstellen, indem beim Erstellen eine der beiden Methoden verwendet wird.
• Die zusätzlichen Informationen aus pyc-Dateien nicht zu laden, wenn diese mit den zusätzlichen Informationen erstellt wurden.
• Die zusätzlichen Informationen beim Anzeigen von Tracebacks zu deaktivieren (die Caret-Zeichen, die den Speicherort des Fehlers anzeigen).

Dies hat einen **sehr geringen** Leistungshitt, da der Interpreterzustand beim Erstellen von Code-Objekten abgerufen werden muss, um die Konfiguration abzufragen. Das Erstellen von Code-Objekten ist keine leistungskritische Operation, daher sollte dies kein Problem darstellen.

Einen einzelnen Caret anstelle eines Bereichs verwenden

Es wurde vorgeschlagen, einen einzelnen Caret anstelle der Hervorhebung des gesamten Bereichs bei der Fehlerberichterstattung zu verwenden, um die Funktion zu vereinfachen. Wir haben uns aus folgenden Gründen gegen diesen Weg entschieden:

• Die Ableitung des Speicherorts des Carets ist anhand des aktuellen AST-Layouts nicht trivial. Dies liegt daran, dass die AST-Knoten nur die Start- und Endzeilennummern sowie die Start- und Endspalten-Offsets aufzeichnen. Da die AST-Knoten die ursprünglichen Tokens nicht beibehalten (designbedingt), ist die Ableitung des genauen Speicherorts einiger Tokens ohne zusätzliches erneutes Parsen nicht möglich. Zum Beispiel haben binäre Operatoren Knoten für die Operanden, aber der Typ des Operators ist in einer Enumeration gespeichert, sodass sein Speicherort nicht vom Knoten abgeleitet werden kann (dies ist nur ein Beispiel dafür, wie dieses Problem auftritt, und nicht das einzige).
• Die Ableitung der Bereiche aus AST-Knoten vereinfacht die Implementierung erheblich und reduziert den Wartungsaufwand und die Fehleranfälligkeit. Dies liegt daran, dass die Verwendung der Bereiche immer generisch für jeden AST-Knoten möglich ist, während jede andere benutzerdefinierte Information unterschiedlich von verschiedenen Knotentypen extrahiert werden müsste. Angesichts der Fehleranfälligkeit der manuellen Standortbestimmung, als dies noch ein manueller Prozess bei der Erzeugung des AST war, glauben wir, dass eine generische Lösung eine sehr wichtige Eigenschaft ist, die verfolgt werden sollte.
• Das Speichern von Informationen zur Hervorhebung eines einzelnen Carets wäre für Tools wie Coverage-Tools und Profiler sowie für Tools wie IPython und IDEs, die diese neue Funktion nutzen möchten, sehr einschränkend. Wie diese Nachricht des Autors von "friendly-traceback" erwähnt, liegt der Grund darin, dass es diesen Tools ohne den vollständigen Bereich (einschließlich Endzeilen) sehr schwer fallen würde, den relevanten Quellcode korrekt hervorzuheben. Zum Beispiel für diesen Code:

  something = foo(a,b,c) if bar(a,b,c) else other(b,c,d)
  

  Tools (wie Coverage-Reporter) möchten den gesamten Aufruf hervorheben können, der vom ausgeführten Bytecode abgedeckt wird (sagen wir foo(a,b,c)) und nicht nur ein einzelnes Zeichen. Auch wenn es technisch möglich wäre, den Quellcode neu zu parsen und zu tokenisieren, um die Informationen zu rekonstruieren, ist dies nicht zuverlässig möglich und würde zu einer viel schlechteren Benutzererfahrung führen.

• Viele Benutzer haben berichtet, dass ein einzelner Caret schwerer zu lesen ist als ein vollständiger Bereich, und dies hat die Verwendung von Bereichen zur Hervorhebung von Syntaxfehlern motiviert, was sehr gut aufgenommen wurde. Zusätzlich wurde festgestellt, dass Benutzer mit Sehproblemen Bereiche viel leichter identifizieren können als ein einzelnes Caret-Zeichen, was wir als großen Vorteil der Verwendung von Bereichen ansehen.

Ein Konfigurationsflag zum Opt-out bereitstellen

Ein Konfigurationsflag zum Opt-out des Overheads, selbst wenn Python im nicht optimierten Modus ausgeführt wird, mag wünschenswert erscheinen, kann aber Probleme beim Lesen von pyc-Dateien verursachen, die mit einer Interpreterversion erstellt wurden, die nicht mit aktiviertem Flag kompiliert wurde. Dies kann zu Abstürzen führen, die für normale Benutzer sehr schwer zu debuggen sind und verschiedene pyc-Dateien inkompatibel zueinander machen. Da diese pycs als Teil von Bibliotheken oder Anwendungen ohne den ursprünglichen Quellcode ausgeliefert werden könnten, ist es auch nicht immer möglich, die Neukompilierung solcher pycs zu erzwingen. Aus diesen Gründen haben wir uns entschieden, das -O-Flag zum Opt-out dieses Verhaltens zu verwenden.

Lazy Loading von Spalteninformationen

Eine mögliche Lösung zur Reduzierung der Speichernutzung dieser Funktion besteht darin, die Spalteninformationen nicht aus der pyc-Datei zu laden, wenn Code importiert wird. Nur wenn eine nicht abgefangene Ausnahme aufsteigt oder ein Aufruf an die C-API-Funktionen erfolgt, werden die Spalteninformationen aus der pyc-Datei geladen. Dies ähnelt der Art und Weise, wie wir nur Quellzeilen lesen, um sie im Traceback anzuzeigen, wenn eine Ausnahme aufsteigt. Dies würde zwar den Speicherverbrauch senken, führt aber auch zu einer wesentlich komplexeren Implementierung, die Änderungen an der Import-Maschinerie erfordert, um einen Teil des Code-Objekts selektiv zu ignorieren. Wir betrachten dies als einen interessanten Weg zur Erkundung, aber letztendlich denken wir, dass es außerhalb des Rahmens dieser speziellen PEP liegt. Es bedeutet auch, dass Spalteninformationen nicht verfügbar sind, wenn der Benutzer keine pyc-Dateien verwendet oder für dynamisch zur Laufzeit erstellte Code-Objekte.

Kompression implementieren

Obwohl es möglich wäre, eine Form der Kompression über die pyc-Dateien und die neuen Daten in Code-Objekten zu implementieren, glauben wir, dass dies aufgrund seiner größeren Auswirkungen (im Fall von pyc-Dateien) und der Tatsache, dass wir erwarten, dass Spalten-Offsets aufgrund des Fehlens von Mustern darin nicht gut komprimieren (im Fall der neuen Daten in Code-Objekten), außerhalb des Rahmens dieses Vorschlags liegt.