diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Fpickletools.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Fpickletools.html | 41 |
1 files changed, 41 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Fpickletools.html b/devdocs/python~3.12/library%2Fpickletools.html new file mode 100644 index 00000000..78f5ed1c --- /dev/null +++ b/devdocs/python~3.12/library%2Fpickletools.html @@ -0,0 +1,41 @@ + <span id="pickletools-tools-for-pickle-developers"></span><h1>pickletools — Tools for pickle developers</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/pickletools.py">Lib/pickletools.py</a></p> <p>This module contains various constants relating to the intimate details of the <a class="reference internal" href="pickle#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code>pickle</code></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#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code>pickle</code></a>; ordinary users of the <a class="reference internal" href="pickle#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code>pickle</code></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."><code>pickletools</code></a> module relevant.</p> <section id="command-line-usage"> <span id="pickletools-cli"></span><h2>Command line usage</h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.2.</span></p> </div> <p>When invoked from the command line, <code>python -m pickletools</code> 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 <code>-m pickle</code> instead. However, when the pickle file that you want to examine comes from an untrusted source, <code>-m pickletools</code> is a safer option because it does not execute pickle bytecode.</p> <p>For example, with a tuple <code>(1, 2)</code> pickled in file <code>x.pickle</code>:</p> <pre data-language="shell">$ 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> <section id="command-line-options"> <h3>Command line options</h3> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-pickletools-a"> +<code>-a, --annotate</code> </dt> <dd> +<p>Annotate each line with a short opcode description.</p> </dd> +</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-pickletools-o"> +<code>-o, --output=<file></code> </dt> <dd> +<p>Name of a file where the output should be written.</p> </dd> +</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-pickletools-l"> +<code>-l, --indentlevel=<num></code> </dt> <dd> +<p>The number of blanks by which to indent a new MARK level.</p> </dd> +</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-pickletools-m"> +<code>-m, --memo</code> </dt> <dd> +<p>When multiple objects are disassembled, preserve memo between disassemblies.</p> </dd> +</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-pickletools-p"> +<code>-p, --preamble=<preamble></code> </dt> <dd> +<p>When more than one pickle file are specified, print given preamble before each disassembly.</p> </dd> +</dl> </section> </section> <section id="programmatic-interface"> <h2>Programmatic Interface</h2> <dl class="py function"> <dt class="sig sig-object py" id="pickletools.dis"> +<code>pickletools.dis(pickle, out=None, memo=None, indentlevel=4, annotate=0)</code> </dt> <dd> +<p>Outputs a symbolic disassembly of the pickle to the file-like object <em>out</em>, defaulting to <code>sys.stdout</code>. <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 <code>MARK</code> 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.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.2: </span>The <em>annotate</em> argument.</p> </div> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="pickletools.genops"> +<code>pickletools.genops(pickle)</code> </dt> <dd> +<p>Provides an <a class="reference internal" href="../glossary#term-iterator"><span class="xref std std-term">iterator</span></a> over all of the opcodes in a pickle, returning a sequence of <code>(opcode, arg, pos)</code> triples. <em>opcode</em> is an instance of an <code>OpcodeInfo</code> 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="py function"> <dt class="sig sig-object py" id="pickletools.optimize"> +<code>pickletools.optimize(picklestring)</code> </dt> <dd> +<p>Returns a new equivalent pickle string after eliminating unused <code>PUT</code> opcodes. The optimized pickle is shorter, takes less transmission time, requires less storage space, and unpickles more efficiently.</p> </dd> +</dl> </section> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/library/pickletools.html" class="_attribution-link">https://docs.python.org/3.12/library/pickletools.html</a> + </p> +</div> |