mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-24 03:35:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Issue #9268: Documented -m pickletools usage.

Browse source 
Also added a source code link.
This commit is contained in:
Alexander Belopolsky 2011-01-13 21:58:44 +00:00
parent d958ea70bc
commit cc75a86123
1 changed files with 64 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

64
Doc/library/pickletools.rst
View file

@ -5,6 +5,11 @@
: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
few useful functions for analyzing pickled data. The contents of this module
@ -12,6 +17,65 @@ 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)