1:mod:`pickletools` --- Tools for pickle developers
2==================================================
3
4.. module:: pickletools
5   :synopsis: Contains extensive comments about the pickle protocols and
6              pickle-machine opcodes, as well as some useful functions.
7
8**Source code:** :source:`Lib/pickletools.py`
9
10--------------
11
12
13This module contains various constants relating to the intimate details of the
14:mod:`pickle` module, some lengthy comments about the implementation, and a
15few useful functions for analyzing pickled data.  The contents of this module
16are useful for Python core developers who are working on the :mod:`pickle`;
17ordinary users of the :mod:`pickle` module probably won't find the
18:mod:`pickletools` module relevant.
19
20Command line usage
21------------------
22
23.. versionadded:: 3.2
24
25When invoked from the command line, ``python -m pickletools`` will
26disassemble the contents of one or more pickle files.  Note that if
27you want to see the Python object stored in the pickle rather than the
28details of pickle format, you may want to use ``-m pickle`` instead.
29However, when the pickle file that you want to examine comes from an
30untrusted source, ``-m pickletools`` is a safer option because it does
31not execute pickle bytecode.
32
33For example, with a tuple ``(1, 2)`` pickled in file ``x.pickle``:
34
35.. code-block:: shell-session
36
37    $ python -m pickle x.pickle
38    (1, 2)
39
40    $ python -m pickletools x.pickle
41        0: \x80 PROTO      3
42        2: K    BININT1    1
43        4: K    BININT1    2
44        6: \x86 TUPLE2
45        7: q    BINPUT     0
46        9: .    STOP
47    highest protocol among opcodes = 2
48
49Command line options
50^^^^^^^^^^^^^^^^^^^^
51
52.. program:: pickletools
53
54.. cmdoption:: -a, --annotate
55
56   Annotate each line with a short opcode description.
57
58.. cmdoption:: -o, --output=<file>
59
60   Name of a file where the output should be written.
61
62.. cmdoption:: -l, --indentlevel=<num>
63
64   The number of blanks by which to indent a new MARK level.
65
66.. cmdoption:: -m, --memo
67
68   When multiple objects are disassembled, preserve memo between
69   disassemblies.
70
71.. cmdoption:: -p, --preamble=<preamble>
72
73   When more than one pickle file are specified, print given preamble
74   before each disassembly.
75
76
77
78Programmatic Interface
79----------------------
80
81
82.. function:: dis(pickle, out=None, memo=None, indentlevel=4, annotate=0)
83
84   Outputs a symbolic disassembly of the pickle to the file-like
85   object *out*, defaulting to ``sys.stdout``.  *pickle* can be a
86   string or a file-like object.  *memo* can be a Python dictionary
87   that will be used as the pickle's memo; it can be used to perform
88   disassemblies across multiple pickles created by the same
89   pickler. Successive levels, indicated by ``MARK`` opcodes in the
90   stream, are indented by *indentlevel* spaces.  If a nonzero value
91   is given to *annotate*, each opcode in the output is annotated with
92   a short description.  The value of *annotate* is used as a hint for
93   the column where annotation should start.
94
95   .. versionadded:: 3.2
96      The *annotate* argument.
97
98.. function:: genops(pickle)
99
100   Provides an :term:`iterator` over all of the opcodes in a pickle, returning a
101   sequence of ``(opcode, arg, pos)`` triples.  *opcode* is an instance of an
102   :class:`OpcodeInfo` class; *arg* is the decoded value, as a Python object, of
103   the opcode's argument; *pos* is the position at which this opcode is located.
104   *pickle* can be a string or a file-like object.
105
106.. function:: optimize(picklestring)
107
108   Returns a new equivalent pickle string after eliminating unused ``PUT``
109   opcodes. The optimized pickle is shorter, takes less transmission time,
110   requires less storage space, and unpickles more efficiently.
111