diff --git a/Doc/library/pickletools.rst b/Doc/library/pickletools.rst index 769ca60af1837e..0a653649a1561b 100644 --- a/Doc/library/pickletools.rst +++ b/Doc/library/pickletools.rst @@ -107,11 +107,47 @@ Programmatic interface .. function:: genops(pickle) Provides an :term:`iterator` over all of the opcodes in a pickle, returning a - sequence of ``(opcode, arg, pos)`` triples. *opcode* is an instance of an - :class:`OpcodeInfo` class; *arg* is the decoded value, as a Python object, of - the opcode's argument; *pos* is the position at which this opcode is located. + sequence of ``(opcode, arg, pos)`` triples. *opcode* is an instance of + :class:`OpcodeInfo`; *arg* is the decoded value, as a Python object, of the + opcode's argument; *pos* is the position at which this opcode is located. *pickle* can be a string or a file-like object. +.. class:: OpcodeInfo + + Represents information about a pickle opcode. + + Instances of this class are returned as the first element of the tuples + yielded by :func:`genops`. + + .. attribute:: name + + The symbolic name of the opcode. + + .. attribute:: code + + The one-character opcode value. + + .. attribute:: arg + + The descriptor for the opcode argument, or ``None`` if the opcode has + no argument. + + .. attribute:: stack_before + + A list describing the stack before the opcode executes. + + .. attribute:: stack_after + + A list describing the stack after the opcode executes. + + .. attribute:: proto + + The pickle protocol version in which the opcode was introduced. + + .. attribute:: doc + + A human-readable description of the opcode. + .. function:: optimize(picklestring) Returns a new equivalent pickle string after eliminating unused ``PUT`` diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 2255c745c00383..6f082cd900a803 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -18,7 +18,6 @@ Doc/library/lzma.rst Doc/library/mmap.rst Doc/library/multiprocessing.rst Doc/library/optparse.rst -Doc/library/pickletools.rst Doc/library/pyexpat.rst Doc/library/select.rst Doc/library/socket.rst diff --git a/Lib/pickletools.py b/Lib/pickletools.py index a9711538dae342..f5c3b2085b6d11 100644 --- a/Lib/pickletools.py +++ b/Lib/pickletools.py @@ -18,7 +18,14 @@ lazy from _colorize import decolor, get_theme -__all__ = ['dis', 'genops', 'optimize'] +__all__ = [ + 'dis', + 'genops', + 'optimize', + 'ArgumentDescriptor', + 'StackObject', + 'OpcodeInfo', +] bytes_types = pickle.bytes_types diff --git a/Lib/test/test_pickletools.py b/Lib/test/test_pickletools.py index caf2d7ba6bfd8f..5716ebdc477153 100644 --- a/Lib/test/test_pickletools.py +++ b/Lib/test/test_pickletools.py @@ -492,7 +492,7 @@ def test__all__(self): 'bytes_types', 'UP_TO_NEWLINE', 'TAKEN_FROM_ARGUMENT1', 'TAKEN_FROM_ARGUMENT4', 'TAKEN_FROM_ARGUMENT4U', - 'TAKEN_FROM_ARGUMENT8U', 'ArgumentDescriptor', + 'TAKEN_FROM_ARGUMENT8U', 'read_uint1', 'read_uint2', 'read_int4', 'read_uint4', 'read_uint8', 'read_stringnl', 'read_stringnl_noescape', 'read_stringnl_noescape_pair', 'read_string1', @@ -508,12 +508,11 @@ def test__all__(self): 'unicodestringnl', 'unicodestring1', 'unicodestring4', 'unicodestring8', 'decimalnl_short', 'decimalnl_long', 'floatnl', 'float8', 'long1', 'long4', - 'StackObject', 'pyint', 'pylong', 'pyinteger_or_bool', 'pybool', 'pyfloat', 'pybytes_or_str', 'pystring', 'pybytes', 'pybytearray', 'pyunicode', 'pynone', 'pytuple', 'pylist', 'pydict', 'pyset', 'pyfrozenset', 'pybuffer', 'anyobject', - 'markobject', 'stackslice', 'OpcodeInfo', 'opcodes', + 'markobject', 'stackslice', 'opcodes', 'code2op', } support.check__all__(self, pickletools, not_exported=not_exported)