diff options
Diffstat (limited to 'Doc/library/pickletools.rst')
| -rw-r--r-- | Doc/library/pickletools.rst | 88 |
1 files changed, 80 insertions, 8 deletions
diff --git a/Doc/library/pickletools.rst b/Doc/library/pickletools.rst index 88ecbab..4c0a148 100644 --- a/Doc/library/pickletools.rst +++ b/Doc/library/pickletools.rst @@ -2,7 +2,13 @@ ================================================== .. module:: pickletools - :synopsis: Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions. + :synopsis: Contains extensive comments about the pickle protocols and + pickle-machine opcodes, as well as some useful functions. + +**Source code:** :source:`Lib/pickletools.py` + +-------------- + This module contains various constants relating to the intimate details of the :mod:`pickle` module, some lengthy comments about the implementation, and a @@ -11,15 +17,81 @@ are useful for Python core developers who are working on the :mod:`pickle`; ordinary users of the :mod:`pickle` module probably won't find the :mod:`pickletools` module relevant. +Command line usage +------------------ + +.. versionadded:: 3.2 + +When invoked from the command line, ``python -m pickletools`` will +disassemble the contents of one or more pickle files. Note that if +you want to see the Python object stored in the pickle rather than the +details of pickle format, you may want to use ``-m pickle`` instead. +However, when the pickle file that you want to examine comes from an +untrusted source, ``-m pickletools`` is a safer option because it does +not execute pickle bytecode. + +For example, with a tuple ``(1, 2)`` pickled in file ``x.pickle``:: + + $ python -m pickle x.pickle + (1, 2) + + $ python -m pickletools x.pickle + 0: \x80 PROTO 3 + 2: K BININT1 1 + 4: K BININT1 2 + 6: \x86 TUPLE2 + 7: q BINPUT 0 + 9: . STOP + highest protocol among opcodes = 2 + +Command line options +^^^^^^^^^^^^^^^^^^^^ + +.. program:: pickletools + +.. cmdoption:: -a, --annotate + + Annotate each line with a short opcode description. + +.. cmdoption:: -o, --output=<file> + + Name of a file where the output should be written. + +.. cmdoption:: -l, --indentlevel=<num> + + The number of blanks by which to indent a new MARK level. + +.. cmdoption:: -m, --memo + + When multiple objects are disassembled, preserve memo between + disassemblies. + +.. cmdoption:: -p, --preamble=<preamble> + + When more than one pickle file are specified, print given preamble + before each disassembly. + + + +Programmatic Interface +---------------------- + + +.. function:: dis(pickle, out=None, memo=None, indentlevel=4, annotate=0) -.. function:: dis(pickle[, out=None, memo=None, indentlevel=4]) + Outputs a symbolic disassembly of the pickle to the file-like + object *out*, defaulting to ``sys.stdout``. *pickle* can be a + string or a file-like object. *memo* can be a Python dictionary + that will be used as the pickle's memo; it can be used to perform + disassemblies across multiple pickles created by the same + pickler. Successive levels, indicated by ``MARK`` opcodes in the + stream, are indented by *indentlevel* spaces. If a nonzero value + is given to *annotate*, each opcode in the output is annotated with + a short description. The value of *annotate* is used as a hint for + the column where annotation should start. - Outputs a symbolic disassembly of the pickle to the file-like object *out*, - defaulting to ``sys.stdout``. *pickle* can be a string or a file-like object. - *memo* can be a Python dictionary that will be used as the pickle's memo; it can - be used to perform disassemblies across multiple pickles created by the same - pickler. Successive levels, indicated by ``MARK`` opcodes in the stream, are - indented by *indentlevel* spaces. + .. versionadded:: 3.2 + The *annotate* argument. .. function:: genops(pickle) |