blob: ea1619040d39e336c0c59ddf6fab91e1b27336ec [file] [log] [blame]
Georg Brandl42a82642009-06-08 07:57:35 +00001:mod:`pickletools` --- Tools for pickle developers
2==================================================
Georg Brandl8ec7f652007-08-15 14:28:01 +00003
4.. module:: pickletools
5 :synopsis: Contains extensive comments about the pickle protocols and pickle-machine
6 opcodes, as well as some useful functions.
7
8
9.. versionadded:: 2.3
10
11This module contains various constants relating to the intimate details of the
12:mod:`pickle` module, some lengthy comments about the implementation, and a few
13useful functions for analyzing pickled data. The contents of this module are
14useful for Python core developers who are working on the :mod:`pickle` and
15:mod:`cPickle` implementations; ordinary users of the :mod:`pickle` module
16probably won't find the :mod:`pickletools` module relevant.
17
18
19.. function:: dis(pickle[, out=None, memo=None, indentlevel=4])
20
21 Outputs a symbolic disassembly of the pickle to the file-like object *out*,
22 defaulting to ``sys.stdout``. *pickle* can be a string or a file-like object.
23 *memo* can be a Python dictionary that will be used as the pickle's memo; it can
24 be used to perform disassemblies across multiple pickles created by the same
25 pickler. Successive levels, indicated by ``MARK`` opcodes in the stream, are
26 indented by *indentlevel* spaces.
27
28
29.. function:: genops(pickle)
30
Georg Brandle7a09902007-10-21 12:10:28 +000031 Provides an :term:`iterator` over all of the opcodes in a pickle, returning a
32 sequence of ``(opcode, arg, pos)`` triples. *opcode* is an instance of an
33 :class:`OpcodeInfo` class; *arg* is the decoded value, as a Python object, of
34 the opcode's argument; *pos* is the position at which this opcode is located.
Georg Brandl8ec7f652007-08-15 14:28:01 +000035 *pickle* can be a string or a file-like object.
36
Raymond Hettingerda614dc2008-02-10 20:35:16 +000037.. function:: optimize(picklestring)
38
39 Returns a new equivalent pickle string after eliminating unused ``PUT``
40 opcodes. The optimized pickle is shorter, takes less transmission time,
41 requires less storage space, and unpickles more efficiently.
42
43 .. versionadded:: 2.6