Doc/library/pickletools.rst

   1
   2 :mod:`pickletools` --- Tools for pickle developers.
   3 ===================================================
   4
   5 .. module:: pickletools
   6    :synopsis: Contains extensive comments about the pickle protocols and pickle-machine
   7               opcodes, as well as some useful functions.
   8
   9
  10 .. versionadded:: 2.3
  11
  12 This module contains various constants relating to the intimate details of the
  13 :mod:`pickle` module, some lengthy comments about the implementation, and a few
  14 useful functions for analyzing pickled data.  The contents of this module are
  15 useful for Python core developers who are working on the :mod:`pickle` and
  16 :mod:`cPickle` implementations; ordinary users of the :mod:`pickle` module
  17 probably won't find the :mod:`pickletools` module relevant.
  18
  19
  20 .. function:: dis(pickle[, out=None, memo=None, indentlevel=4])
  21
  22    Outputs a symbolic disassembly of the pickle to the file-like object *out*,
  23    defaulting to ``sys.stdout``.  *pickle* can be a string or a file-like object.
  24    *memo* can be a Python dictionary that will be used as the pickle's memo; it can
  25    be used to perform disassemblies across multiple pickles created by the same
  26    pickler. Successive levels, indicated by ``MARK`` opcodes in the stream, are
  27    indented by *indentlevel* spaces.
  28
  29
  30 .. function:: genops(pickle)
  31
  32    Provides an :term:`iterator` over all of the opcodes in a pickle, returning a
  33    sequence of ``(opcode, arg, pos)`` triples.  *opcode* is an instance of an
  34    :class:`OpcodeInfo` class; *arg* is the decoded value, as a Python object, of
  35    the opcode's argument; *pos* is the position at which this opcode is located.
  36    *pickle* can be a string or a file-like object.
  37