pickletools — Werkzeuge für Entwickler von pickle

Quellcode: Lib/pickletools.py

Dieses Modul enthält verschiedene Konstanten zu den internen Einzelheiten des Moduls pickle, einige ausführliche Kommentare zur Implementierung sowie ein paar nützliche Funktionen zur Analyse serialisierter Daten. Der Inhalt dieses Moduls ist für Python-Kernentwickler nützlich, die an pickle arbeiten. Für normale Nutzer des Moduls pickle dürfte das Modul pickletools kaum von Bedeutung sein.

Verwendung auf der Kommandozeile

Added in version 3.2.

Beim Aufruf über die Kommandozeile zerlegt python -m pickletools den Inhalt einer oder mehrerer Pickle-Dateien. Beachte: Wenn du das im Pickle gespeicherte Python-Objekt sehen möchtest statt der Einzelheiten des Pickle-Formats, ist -m pickle die bessere Wahl. Stammt die zu untersuchende Pickle-Datei jedoch aus einer nicht vertrauenswürdigen Quelle, ist -m pickletools die sicherere Möglichkeit, weil dabei kein Pickle-Bytecode ausgeführt wird.

Zum Beispiel mit einem Tupel (1, 2), das in der Datei x.pickle gepickelt wurde:

$ python -m pickle x.pickle
(1, 2)

$ python -m pickletools x.pickle
    0: \x80 PROTO      3
    2: K    BININT1    1
    4: K    BININT1    2
    6: \x86 TUPLE2
    7: q    BINPUT     0
    9: .    STOP
highest protocol among opcodes = 2

Kommandozeilenoptionen

-a, --annotate

Versieht jede Zeile mit einer kurzen Beschreibung des Opcodes.

-o, --output=<file>

Name einer Datei, in die die Ausgabe geschrieben werden soll.

-l, --indentlevel=<num>

Die Anzahl der Leerzeichen, um die eine neue MARK-Ebene eingerückt wird.

-m, --memo

Behält bei der Zerlegung mehrerer Objekte das Memo zwischen den Zerlegungen bei.

-p, --preamble=<preamble>

Gibt bei mehreren angegebenen Pickle-Dateien vor jeder Zerlegung die angegebene Präambel aus.

pickle_file

Eine einzulesende Pickle-Datei oder -, um von der Standardeingabe zu lesen.

Added in version 3.15: Die Ausgabe erfolgt standardmäßig farbig und lässt sich über Umgebungsvariablen steuern.

Programmierschnittstelle

pickletools.dis(pickle, out=None, memo=None, indentlevel=4, annotate=0)

Gibt eine symbolische Zerlegung des Pickles in das dateiähnliche Objekt out aus, standardmäßig sys.stdout. pickle kann eine Zeichenkette oder ein dateiähnliches Objekt sein. memo kann ein Python-Dictionary sein, das als Memo des Pickles verwendet wird. Damit lassen sich mehrere Pickles zerlegen, die vom selben Pickler erzeugt wurden. Aufeinanderfolgende Ebenen, die im Strom durch MARK-Opcodes gekennzeichnet sind, werden um indentlevel Leerzeichen eingerückt. Wird für annotate ein Wert ungleich null angegeben, erhält jeder Opcode in der Ausgabe eine kurze Beschreibung. Der Wert von annotate dient als Hinweis auf die Spalte, in der die Beschreibung beginnen soll.

Geändert in Version 3.2: Der Parameter annotate wurde hinzugefügt.

pickletools.genops(pickle)

Stellt einen Iterator über alle Opcodes in einem Pickle bereit und liefert eine Folge von Tripeln der Form (opcode, arg, pos). opcode ist eine Instanz der Klasse OpcodeInfo; arg ist der dekodierte Wert des Opcode-Arguments als Python-Objekt; pos ist die Position, an der sich dieser Opcode befindet. pickle kann eine Zeichenkette oder ein dateiähnliches Objekt sein.

pickletools.optimize(picklestring)

Gibt eine neue, gleichwertige Pickle-Zeichenkette zurück, nachdem ungenutzte PUT-Opcodes entfernt wurden. Das optimierte Pickle ist kürzer, benötigt weniger Übertragungszeit und Speicherplatz und lässt sich effizienter wieder einlesen.