| 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 |
.. _pickletools-cli: |
| 21 |
|
| 22 |
Command-line usage |
| 23 |
------------------ |
| 24 |
|
| 25 |
.. versionadded:: 3.2 |
| 26 |
|
| 27 |
When invoked from the command line, ``python -m pickletools`` will |
| 28 |
disassemble the contents of one or more pickle files. Note that if |
| 29 |
you want to see the Python object stored in the pickle rather than the |
| 30 |
details of pickle format, you may want to use ``-m pickle`` instead. |
| 31 |
However, when the pickle file that you want to examine comes from an |
| 32 |
untrusted source, ``-m pickletools`` is a safer option because it does |
| 33 |
not execute pickle bytecode. |
| 34 |
|
| 35 |
For example, with a tuple ``(1, 2)`` pickled in file ``x.pickle``: |
| 36 |
|
| 37 |
.. code-block:: shell-session |
| 38 |
|
| 39 |
$ python -m pickle x.pickle |
| 40 |
(1, 2) |
| 41 |
|
| 42 |
$ python -m pickletools x.pickle |
| 43 |
0: \x80 PROTO 3 |
| 44 |
2: K BININT1 1 |
| 45 |
4: K BININT1 2 |
| 46 |
6: \x86 TUPLE2 |
| 47 |
7: q BINPUT 0 |
| 48 |
9: . STOP |
| 49 |
highest protocol among opcodes = 2 |
| 50 |
|
| 51 |
Command-line options |
| 52 |
^^^^^^^^^^^^^^^^^^^^ |
| 53 |
|
| 54 |
.. program:: pickletools |
| 55 |
|
| 56 |
.. option:: -a, --annotate |
| 57 |
|
| 58 |
Annotate each line with a short opcode description. |
| 59 |
|
| 60 |
.. option:: -o, --output=<file> |
| 61 |
|
| 62 |
Name of a file where the output should be written. |
| 63 |
|
| 64 |
.. option:: -l, --indentlevel=<num> |
| 65 |
|
| 66 |
The number of blanks by which to indent a new MARK level. |
| 67 |
|
| 68 |
.. option:: -m, --memo |
| 69 |
|
| 70 |
When multiple objects are disassembled, preserve memo between |
| 71 |
disassemblies. |
| 72 |
|
| 73 |
.. option:: -p, --preamble=<preamble> |
| 74 |
|
| 75 |
When more than one pickle file is specified, print given preamble |
| 76 |
before each disassembly. |
| 77 |
|
| 78 |
.. option:: pickle_file |
| 79 |
|
| 80 |
A pickle file to read, or ``-`` to indicate reading from standard input. |
| 81 |
|
| 82 |
|
| 83 |
|
| 84 |
Programmatic interface |
| 85 |
---------------------- |
| 86 |
|
| 87 |
|
| 88 |
.. function:: dis(pickle, out=None, memo=None, indentlevel=4, annotate=0) |
| 89 |
|
| 90 |
Outputs a symbolic disassembly of the pickle to the file-like |
| 91 |
object *out*, defaulting to ``sys.stdout``. *pickle* can be a |
| 92 |
string or a file-like object. *memo* can be a Python dictionary |
| 93 |
that will be used as the pickle's memo; it can be used to perform |
| 94 |
disassemblies across multiple pickles created by the same |
| 95 |
pickler. Successive levels, indicated by ``MARK`` opcodes in the |
| 96 |
stream, are indented by *indentlevel* spaces. If a nonzero value |
| 97 |
is given to *annotate*, each opcode in the output is annotated with |
| 98 |
a short description. The value of *annotate* is used as a hint for |
| 99 |
the column where annotation should start. |
| 100 |
|
| 101 |
.. versionchanged:: 3.2 |
| 102 |
Added the *annotate* parameter. |
| 103 |
|
| 104 |
.. function:: genops(pickle) |
| 105 |
|
| 106 |
Provides an :term:`iterator` over all of the opcodes in a pickle, returning a |
| 107 |
sequence of ``(opcode, arg, pos)`` triples. *opcode* is an instance of an |
| 108 |
:class:`OpcodeInfo` class; *arg* is the decoded value, as a Python object, of |
| 109 |
the opcode's argument; *pos* is the position at which this opcode is located. |
| 110 |
*pickle* can be a string or a file-like object. |
| 111 |
|
| 112 |
.. function:: optimize(picklestring) |
| 113 |
|
| 114 |
Returns a new equivalent pickle string after eliminating unused ``PUT`` |
| 115 |
opcodes. The optimized pickle is shorter, takes less transmission time, |
| 116 |
requires less storage space, and unpickles more efficiently. |