pickletools — Tools for pickle developers

Source code:Lib/pickletools.py

This module contains various constants relating to the intimate details of thepickle module, some lengthy comments about the implementation, and afew useful functions for analyzing pickled data. The contents of this moduleare useful for Python core developers who are working on thepickle;ordinary users of thepickle module probably won’t find thepickletools module relevant.

Command-line usage

Added in version 3.2.

When invoked from the command line,python-mpickletools willdisassemble the contents of one or more pickle files. Note that ifyou want to see the Python object stored in the pickle rather than thedetails of pickle format, you may want to use-mpickle instead.However, when the pickle file that you want to examine comes from anuntrusted source,-mpickletools is a safer option because it doesnot execute pickle bytecode.

For example, with a tuple(1,2) pickled in filex.pickle:

$python-mpicklex.pickle(1, 2)$python-mpickletoolsx.pickle    0: \x80 PROTO      3    2: K    BININT1    1    4: K    BININT1    2    6: \x86 TUPLE2    7: q    BINPUT     0    9: .    STOPhighest protocol among opcodes = 2

Command-line options

-a,--annotate

Annotate each line with a short opcode description.

-o,--output=<file>

Name of a file where the output should be written.

-l,--indentlevel=<num>

The number of blanks by which to indent a new MARK level.

-m,--memo

When multiple objects are disassembled, preserve memo betweendisassemblies.

-p,--preamble=<preamble>

When more than one pickle file is specified, print given preamblebefore each disassembly.

pickle_file

A pickle file to read, or- to indicate reading from standard input.

Programmatic interface

pickletools.dis(pickle,out=None,memo=None,indentlevel=4,annotate=0)

Outputs a symbolic disassembly of the pickle to the file-likeobjectout, defaulting tosys.stdout.pickle can be astring or a file-like object.memo can be a Python dictionarythat will be used as the pickle’s memo; it can be used to performdisassemblies across multiple pickles created by the samepickler. Successive levels, indicated byMARK opcodes in thestream, are indented byindentlevel spaces. If a nonzero valueis given toannotate, each opcode in the output is annotated witha short description. The value ofannotate is used as a hint forthe column where annotation should start.

Changed in version 3.2:Added theannotate parameter.

pickletools.genops(pickle)

Provides aniterator over all of the opcodes in a pickle, returning asequence of(opcode,arg,pos) triples.opcode is an instance of anOpcodeInfo class;arg is the decoded value, as a Python object, ofthe opcode’s argument;pos is the position at which this opcode is located.pickle can be a string or a file-like object.

pickletools.optimize(picklestring)

Returns a new equivalent pickle string after eliminating unusedPUTopcodes. The optimized pickle is shorter, takes less transmission time,requires less storage space, and unpickles more efficiently.