Misc tweaks and updates.

pep-0307.txt

@@ -26,6 +26,12 @@ Introduction
     the standard library module pickletools.py (already checked into
     CVS for Python 2.3).
 
+    This PEP attempts to fully document the interface between pickled
+    objects and the pickling process, highlighting additions by
+    specifying "new in this PEP".  (The interface to invoke pickling
+    or unpickling is not covered fully, except for the changes to the
+    API for specifying the pickling protocol to picklers.)
+
 
 Motivation
 
@@ -78,6 +84,15 @@ Protocol versions
     highest protocol version supported by a particular implementation.
     This works in previous Python versions, too.
 
+    The pickle.py module has supported passing the 'bin' value as a
+    keyword argument rather than a positional argument.  (This is not
+    recommended, since cPickle only accepts positional arguments, but
+    it works...)  Passing 'bin' as a keyword argument is deprecated,
+    and a PendingDeprecationWarning is issued in this case.  You have
+    to invoke the Python interpreter with -Wa or a variation on that
+    to see PendingDeprecationWarning messages.  In Python 2.4, the
+    warning class may be upgraded to DeprecationWarning.
+
 
 Security issues
 
@@ -105,6 +120,9 @@ Security issues
       *** Do not unpickle data received from an untrusted or
           unauthenticated source ***
 
+    The same warning applies to previous Python versions, despite the
+    presence of safety checks there.
+
 
 Extended __reduce__ API
 
@@ -184,6 +202,15 @@ Extended __reduce__ API
     2.3, __setstate__ will never be called when __reduce__ returns a
     state with value None.
 
+    A __reduce__ implementation that needs to work both under Python
+    2.2 and under Python 2.3 could check the variable
+    pickle.format_version to determine whether to use the listitems
+    and dictitems features.  If this value is >= "2.0" then they are
+    supported.  If not, any list or dict items should be incorporated
+    somehow in the 'state' return value; the __setstate__ method
+    should be prepared to accept list or dict items as part of the
+    state (how this is done is up to the application).
+
 
 The __newobj__ unpickling function
 
@@ -205,6 +232,10 @@ The __newobj__ unpickling function
     function named __newobj__ that returns something different, you
     deserve what you get.
 
+    It is safe to use this feature under Python 2.2; there's nothing
+    in the recommended implementation of __newobj__ that depends on
+    Python 2.3.
+
 
 TBD