"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.
