<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>30.13. pickletools — Tools for pickle developers — Python v3.2.2 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '3.2.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python v3.2.2 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Python v3.2.2 documentation" href="../index.html" />
<link rel="up" title="30. Python Language Services" href="language.html" />
<link rel="next" title="31. Miscellaneous Services" href="misc.html" />
<link rel="prev" title="30.12. dis — Disassembler for Python bytecode" href="dis.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="misc.html" title="31. Miscellaneous Services"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="dis.html" title="30.12. dis — Disassembler for Python bytecode"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v3.2.2 documentation</a> »</li>
<li><a href="index.html" >The Python Standard Library</a> »</li>
<li><a href="language.html" accesskey="U">30. Python Language Services</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-pickletools">
<span id="pickletools-tools-for-pickle-developers"></span><h1>30.13. <a class="reference internal" href="#module-pickletools" title="pickletools: Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions."><tt class="xref py py-mod docutils literal"><span class="pre">pickletools</span></tt></a> — Tools for pickle developers<a class="headerlink" href="#module-pickletools" title="Permalink to this headline">¶</a></h1>
<p><strong>Source code:</strong> <a class="reference external" href="http://hg.python.org/cpython/file/3.2/Lib/pickletools.py">Lib/pickletools.py</a></p>
<hr class="docutils" />
<p>This module contains various constants relating to the intimate details of the
<a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><tt class="xref py py-mod docutils literal"><span class="pre">pickle</span></tt></a> 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 <a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><tt class="xref py py-mod docutils literal"><span class="pre">pickle</span></tt></a>;
ordinary users of the <a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><tt class="xref py py-mod docutils literal"><span class="pre">pickle</span></tt></a> module probably won’t find the
<a class="reference internal" href="#module-pickletools" title="pickletools: Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions."><tt class="xref py py-mod docutils literal"><span class="pre">pickletools</span></tt></a> module relevant.</p>
<div class="section" id="command-line-usage">
<h2>30.13.1. Command line usage<a class="headerlink" href="#command-line-usage" title="Permalink to this headline">¶</a></h2>
<p class="versionadded">
<span class="versionmodified">New in version 3.2.</span></p>
<p>When invoked from the command line, <tt class="docutils literal"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">pickletools</span></tt> 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 <tt class="docutils literal"><span class="pre">-m</span> <span class="pre">pickle</span></tt> instead.
However, when the pickle file that you want to examine comes from an
untrusted source, <tt class="docutils literal"><span class="pre">-m</span> <span class="pre">pickletools</span></tt> is a safer option because it does
not execute pickle bytecode.</p>
<p>For example, with a tuple <tt class="docutils literal"><span class="pre">(1,</span> <span class="pre">2)</span></tt> pickled in file <tt class="docutils literal"><span class="pre">x.pickle</span></tt>:</p>
<div class="highlight-python3"><pre>$ 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</pre>
</div>
<div class="section" id="command-line-options">
<h3>30.13.1.1. Command line options<a class="headerlink" href="#command-line-options" title="Permalink to this headline">¶</a></h3>
<dl class="cmdoption">
<dt id="cmdoption-pickletools-a">
<tt class="descname">-a</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--annotate</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-pickletools-a" title="Permalink to this definition">¶</a></dt>
<dd><p>Annotate each line with a short opcode description.</p>
</dd></dl>
<dl class="cmdoption">
<dt id="cmdoption-pickletools-o">
<tt class="descname">-o</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--output</tt><tt class="descclassname">=<file></tt><a class="headerlink" href="#cmdoption-pickletools-o" title="Permalink to this definition">¶</a></dt>
<dd><p>Name of a file where the output should be written.</p>
</dd></dl>
<dl class="cmdoption">
<dt id="cmdoption-pickletools-l">
<tt class="descname">-l</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--indentlevel</tt><tt class="descclassname">=<num></tt><a class="headerlink" href="#cmdoption-pickletools-l" title="Permalink to this definition">¶</a></dt>
<dd><p>The number of blanks by which to indent a new MARK level.</p>
</dd></dl>
<dl class="cmdoption">
<dt id="cmdoption-pickletools-m">
<tt class="descname">-m</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--memo</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-pickletools-m" title="Permalink to this definition">¶</a></dt>
<dd><p>When multiple objects are disassembled, preserve memo between
disassemblies.</p>
</dd></dl>
<dl class="cmdoption">
<dt id="cmdoption-pickletools-p">
<tt class="descname">-p</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--preamble</tt><tt class="descclassname">=<preamble></tt><a class="headerlink" href="#cmdoption-pickletools-p" title="Permalink to this definition">¶</a></dt>
<dd><p>When more than one pickle file are specified, print given preamble
before each disassembly.</p>
</dd></dl>
</div>
</div>
<div class="section" id="programmatic-interface">
<h2>30.13.2. Programmatic Interface<a class="headerlink" href="#programmatic-interface" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="pickletools.dis">
<tt class="descclassname">pickletools.</tt><tt class="descname">dis</tt><big>(</big><em>pickle</em>, <em>out=None</em>, <em>memo=None</em>, <em>indentlevel=4</em>, <em>annotate=0</em><big>)</big><a class="headerlink" href="#pickletools.dis" title="Permalink to this definition">¶</a></dt>
<dd><blockquote>
<div>Outputs a symbolic disassembly of the pickle to the file-like
object <em>out</em>, defaulting to <tt class="docutils literal"><span class="pre">sys.stdout</span></tt>. <em>pickle</em> can be a
string or a file-like object. <em>memo</em> 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 <tt class="docutils literal"><span class="pre">MARK</span></tt> opcodes in the
stream, are indented by <em>indentlevel</em> spaces. If a nonzero value
is given to <em>annotate</em>, each opcode in the output is annotated with
a short description. The value of <em>annotate</em> is used as a hint for
the column where annotation should start.</div></blockquote>
<p class="versionadded">
<span class="versionmodified">New in version 3.2: </span>The <em>annotate</em> argument.</p>
</dd></dl>
<dl class="function">
<dt id="pickletools.genops">
<tt class="descclassname">pickletools.</tt><tt class="descname">genops</tt><big>(</big><em>pickle</em><big>)</big><a class="headerlink" href="#pickletools.genops" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides an <a class="reference internal" href="../glossary.html#term-iterator"><em class="xref std std-term">iterator</em></a> over all of the opcodes in a pickle, returning a
sequence of <tt class="docutils literal"><span class="pre">(opcode,</span> <span class="pre">arg,</span> <span class="pre">pos)</span></tt> triples. <em>opcode</em> is an instance of an
<tt class="xref py py-class docutils literal"><span class="pre">OpcodeInfo</span></tt> class; <em>arg</em> is the decoded value, as a Python object, of
the opcode’s argument; <em>pos</em> is the position at which this opcode is located.
<em>pickle</em> can be a string or a file-like object.</p>
</dd></dl>
<dl class="function">
<dt id="pickletools.optimize">
<tt class="descclassname">pickletools.</tt><tt class="descname">optimize</tt><big>(</big><em>picklestring</em><big>)</big><a class="headerlink" href="#pickletools.optimize" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a new equivalent pickle string after eliminating unused <tt class="docutils literal"><span class="pre">PUT</span></tt>
opcodes. The optimized pickle is shorter, takes less transmission time,
requires less storage space, and unpickles more efficiently.</p>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">30.13. <tt class="docutils literal"><span class="pre">pickletools</span></tt> — Tools for pickle developers</a><ul>
<li><a class="reference internal" href="#command-line-usage">30.13.1. Command line usage</a><ul>
<li><a class="reference internal" href="#command-line-options">30.13.1.1. Command line options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#programmatic-interface">30.13.2. Programmatic Interface</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="dis.html"
title="previous chapter">30.12. <tt class="docutils literal docutils literal docutils literal"><span class="pre">dis</span></tt> — Disassembler for Python bytecode</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="misc.html"
title="next chapter">31. Miscellaneous Services</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li><a href="../_sources/library/pickletools.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="misc.html" title="31. Miscellaneous Services"
>next</a> |</li>
<li class="right" >
<a href="dis.html" title="30.12. dis — Disassembler for Python bytecode"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v3.2.2 documentation</a> »</li>
<li><a href="index.html" >The Python Standard Library</a> »</li>
<li><a href="language.html" >30. Python Language Services</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2011, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="http://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Sep 04, 2011.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.1
>
x86_64
>
media
>
contrib-backports
>
by-pkgid
>
3ba3bd1608c672ba2129b098a48e9e4d
>
files
>
760
