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 Command line usage 21 ------------------ 22 23 .. versionadded:: 3.2 24 25 When invoked from the command line, ``python -m pickletools`` will 26 disassemble the contents of one or more pickle files. Note that if 27 you want to see the Python object stored in the pickle rather than the 28 details of pickle format, you may want to use ``-m pickle`` instead. 29 However, when the pickle file that you want to examine comes from an 30 untrusted source, ``-m pickletools`` is a safer option because it does 31 not execute pickle bytecode. 32 33 For 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 49 Command 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 78 Programmatic 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
