[Bug #873146] Document pickletools module (haven't tested the LaTeX yet)

diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 8895b578321d8c0b4f98f5ccf4df4f031fceb8f2..6704d102d5567307e5b9b5dd117891a1861711a6 100644 (file)
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -322,6 +322,7 @@ and how to embed it in other applications.
 \input{libpycompile}            % really py_compile
 \input{libcompileall}
 \input{libdis}
+\input{libpickletools}
 \input{distutils}
 
 \input{compiler}                % compiler package

diff --git a/Doc/lib/libpickletools.tex b/Doc/lib/libpickletools.tex
new file mode 100644 (file)
index 0000000..0fe76ff
--- /dev/null
+++ b/Doc/lib/libpickletools.tex
@@ -0,0 +1,32 @@
+\section{\module{pickletools} --- Tools for pickle developers.}
+
+\declaremodule{standard}{pickletools}
+\modulesynopsis{Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions.}
+
+This module contains various constants relating to the intimate
+details of the \refmodule{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 \module{pickle} and \module{cPickle}
+implementations; ordinary users of the \module{pickle} module probably
+won't find the \module{pickletools} module relevant.
+
+\begin{funcdesc}{dis}{pickle\optional{, out=None, memo=None, indentlevel=4}}
+Outputs a symbolic disassembly of the pickle to the file-like object
+\var{out}, defaulting to \code{sys.stdout}.  \var{pickle} can be a
+string or a file-like object.  \var{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 \code{MARK} opcodes in the stream, are
+indented by \var{indentlevel} spaces.
+\end{funcdesc}
+
+\begin{funcdesc}{genops}{pickle}
+Provides an iterator over all of the opcodes in a pickle, returning a
+sequence of \code{(\var{opcode}, \var{arg}, \var{pos})} triples.
+\var{opcode} is an instance of an \class{OpcodeInfo} class; \var{arg} 
+is the decoded value, as a Python object, of the opcode's argument; 
+\var{pos} is the position at which this opcode is located.
+\var{pickle} can be a string or a file-like object.
+\end{funcdesc}
+