Added a brief comment to each pickle opcode declaration.

Lib/pickle.py

@@ -2,6 +2,7 @@
 
 See module cPickle for a (much) faster implementation.
 See module copy_reg for a mechanism for registering custom picklers.
+See module pickletools source for extensive comments.
 
 Classes:
 
@@ -77,50 +78,54 @@ try:
 except NameError:
     UnicodeType = None
 
+# Pickle opcodes.  See pickletools.py for extensive docs.  The listing
+# here is in kind-of alphabetical order of 1-character pickle code.
+# pickletools groups them by purpose.
 
-MARK            = '('
+MARK            = '('   # push special markobject on stack
-STOP            = '.'
+STOP            = '.'   # every pickle ends with STOP
-POP             = '0'
+POP             = '0'   # discard topmost stack item
-POP_MARK        = '1'
+POP_MARK        = '1'   # discard stack top through topmost markobject
-DUP             = '2'
+DUP             = '2'   # duplicate top stack item
-FLOAT           = 'F'
+FLOAT           = 'F'   # push float object; decimal string argument
-INT             = 'I'
+INT             = 'I'   # push integer or bool; decimal string argument
-BININT          = 'J'
+BININT          = 'J'   # push four-byte signed int
-BININT1         = 'K'
+BININT1         = 'K'   # push 1-byte unsigned int
-LONG            = 'L'
+LONG            = 'L'   # push long; decimal string argument
-BININT2         = 'M'
+BININT2         = 'M'   # push 2-byte unsigned int
-NONE            = 'N'
+NONE            = 'N'   # push None
-PERSID          = 'P'
+PERSID          = 'P'   # push persistent object; id is taken from string arg
-BINPERSID       = 'Q'
+BINPERSID       = 'Q'   #  "       "         "  ;  "  "   "     "  stack
-REDUCE          = 'R'
+REDUCE          = 'R'   # apply callable to argtuple, both on stack
-STRING          = 'S'
+STRING          = 'S'   # push string; NL-terminated string argument
-BINSTRING       = 'T'
+BINSTRING       = 'T'   # push string; counted binary string argument
-SHORT_BINSTRING = 'U'
+SHORT_BINSTRING = 'U'   #  "     "   ;    "      "       "      " < 256 bytes
-UNICODE         = 'V'
+UNICODE         = 'V'   # push Unicode string; raw-unicode-escaped'd argument
-BINUNICODE      = 'X'
+BINUNICODE      = 'X'   #   "     "       "  ; counted UTF-8 string argument
-APPEND          = 'a'
+APPEND          = 'a'   # append stack top to list below it
-BUILD           = 'b'
+BUILD           = 'b'   # call __setstate__ or __dict__.update()
-GLOBAL          = 'c'
+GLOBAL          = 'c'   # push self.find_class(modname, name); 2 string args
-DICT            = 'd'
+DICT            = 'd'   # build a dict from stack items
-EMPTY_DICT      = '}'
+EMPTY_DICT      = '}'   # push empty dict
-APPENDS         = 'e'
+APPENDS         = 'e'   # extend list on stack by topmost stack slice
-GET             = 'g'
+GET             = 'g'   # push item from memo on stack; index is string arg
-BINGET          = 'h'
+BINGET          = 'h'   #   "    "    "    "   "   "  ;   "    " 1-byte arg
-INST            = 'i'
+INST            = 'i'   # build & push class instance
-LONG_BINGET     = 'j'
+LONG_BINGET     = 'j'   # push item from memo on stack; index is 4-byte arg
-LIST            = 'l'
+LIST            = 'l'   # build list from topmost stack items
-EMPTY_LIST      = ']'
+EMPTY_LIST      = ']'   # push empty list
-OBJ             = 'o'
+OBJ             = 'o'   # build & push class instance
-PUT             = 'p'
+PUT             = 'p'   # store stack top in memo; index is string arg
-BINPUT          = 'q'
+BINPUT          = 'q'   #   "     "    "   "   " ;   "    " 1-byte arg
-LONG_BINPUT     = 'r'
+LONG_BINPUT     = 'r'   #   "     "    "   "   " ;   "    " 4-byte arg
-SETITEM         = 's'
+SETITEM         = 's'   # add key+value pair to dict
-TUPLE           = 't'
+TUPLE           = 't'   # build tuple from topmost stack items
-EMPTY_TUPLE     = ')'
+EMPTY_TUPLE     = ')'   # push empty tuple
-SETITEMS        = 'u'
+SETITEMS        = 'u'   # modify dict by adding topmost key+value pairs
-BINFLOAT        = 'G'
+BINFLOAT        = 'G'   # push float; arg is 8-byte float encoding
-TRUE            = 'I01\n'
+
-FALSE           = 'I00\n'
+TRUE            = 'I01\n'  # not an opcode; see INT docs in pickletools.py
+FALSE           = 'I00\n'  # not an opcode; see INT docs in pickletools.py
 
 
 __all__.extend([x for x in dir() if re.match("[A-Z][A-Z0-9_]+$",x)])
@@ -303,7 +308,7 @@ class Pickler:
         if not callable(acallable):
             raise PicklingError("__reduce__() must return callable as "
                                 "first argument, not %s" % `acallable`)
-        
+
         save(acallable)
         save(arg_tup)
         write(REDUCE)