"pickletools" --- Tools for pickle developers
*********************************************

**Quellcode:** Lib/pickletools.py

======================================================================

This module contains various constants relating to the intimate
details of the "pickle" module, some lengthy comments about the
implementation, and a few useful functions for analyzing pickled data.
The contents of this module are useful for Python core developers who
are working on the "pickle"; ordinary users of the "pickle" module
probably won't find the "pickletools" module relevant.


Command line usage
==================

Neu 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


Command line options
--------------------

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

   When more than one pickle file are specified, print given preamble
   before each disassembly.


Programmatic Interface
======================

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.

   Neu in Version 3.2: The *annotate* argument.

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.
