Georg Brandl | 0eaab97 | 2009-06-08 08:00:22 +0000 | [diff] [blame] | 1 | :mod:`pickletools` --- Tools for pickle developers |
| 2 | ================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: pickletools |
Alexandre Vassalotti | ffcec43 | 2009-04-03 06:07:29 +0000 | [diff] [blame] | 5 | :synopsis: Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | This module contains various constants relating to the intimate details of the |
Alexandre Vassalotti | ffcec43 | 2009-04-03 06:07:29 +0000 | [diff] [blame] | 8 | :mod:`pickle` module, some lengthy comments about the implementation, and a |
| 9 | few useful functions for analyzing pickled data. The contents of this module |
| 10 | are useful for Python core developers who are working on the :mod:`pickle`; |
| 11 | ordinary users of the :mod:`pickle` module probably won't find the |
| 12 | :mod:`pickletools` module relevant. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
| 14 | |
| 15 | .. function:: dis(pickle[, out=None, memo=None, indentlevel=4]) |
| 16 | |
| 17 | Outputs a symbolic disassembly of the pickle to the file-like object *out*, |
| 18 | defaulting to ``sys.stdout``. *pickle* can be a string or a file-like object. |
| 19 | *memo* can be a Python dictionary that will be used as the pickle's memo; it can |
| 20 | be used to perform disassemblies across multiple pickles created by the same |
| 21 | pickler. Successive levels, indicated by ``MARK`` opcodes in the stream, are |
| 22 | indented by *indentlevel* spaces. |
| 23 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | .. function:: genops(pickle) |
| 25 | |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 26 | Provides an :term:`iterator` over all of the opcodes in a pickle, returning a |
| 27 | sequence of ``(opcode, arg, pos)`` triples. *opcode* is an instance of an |
| 28 | :class:`OpcodeInfo` class; *arg* is the decoded value, as a Python object, of |
| 29 | the opcode's argument; *pos* is the position at which this opcode is located. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | *pickle* can be a string or a file-like object. |
| 31 | |
Christian Heimes | 3feef61 | 2008-02-11 06:19:17 +0000 | [diff] [blame] | 32 | .. function:: optimize(picklestring) |
| 33 | |
| 34 | Returns a new equivalent pickle string after eliminating unused ``PUT`` |
| 35 | opcodes. The optimized pickle is shorter, takes less transmission time, |
| 36 | requires less storage space, and unpickles more efficiently. |
| 37 | |