Debian Codegraph @

Doc/library/pickletools.rst

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