Issue #9268: Documented -m pickletools usage.

abalkin · abalkin · commit cc75a86123eb · 2011-01-13T21:58:44.000Z
Also added a source code link.
diff --git a/Doc/library/pickletools.rst b/Doc/library/pickletools.rst
@@ -5,13 +5,77 @@
    :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
 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)
 
