Doc/library/pickletools.rst

   1 :mod:`pickletools` --- Tools for pickle developers
   2 ==================================================
   3
   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
  11 This module contains various constants relating to the intimate details of the
  12 :mod:`pickle` module, some lengthy comments about the implementation, and a few
  13 useful functions for analyzing pickled data.  The contents of this module are
  14 useful for Python core developers who are working on the :mod:`pickle` and
  15 :mod:`cPickle` implementations; ordinary users of the :mod:`pickle` module
  16 probably 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
  31    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.
  35    *pickle* can be a string or a file-like object.
  36
  37 .. 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