[Python-checkins] r87990 - python/branches/py3k/Doc/library/pickletools.rst

[alexander.belopolsky]

Author: alexander.belopolsky
Date: Thu Jan 13 22:58:44 2011
New Revision: 87990

Log:
Issue #9268: Documented -m pickletools usage.

Also added a source code link.



Modified:
   python/branches/py3k/Doc/library/pickletools.rst

Modified: python/branches/py3k/Doc/library/pickletools.rst
==============================================================================
--- python/branches/py3k/Doc/library/pickletools.rst	(original)
+++ python/branches/py3k/Doc/library/pickletools.rst	Thu Jan 13 22:58:44 2011
@@ -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 @@
 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)