[Python-checkins] python/nondist/peps pep-0307.txt,1.3,1.4

[gvanrossum@users.sourceforge.net]

Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1:/tmp/cvs-serv13121

Modified Files:
	pep-0307.txt 
Log Message:
Document extended __reduce__ API.


Index: pep-0307.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0307.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** pep-0307.txt	31 Jan 2003 21:13:18 -0000	1.3
--- pep-0307.txt	31 Jan 2003 21:58:34 -0000	1.4
***************
*** 107,110 ****
--- 107,188 ----
  
  
+ Extended __reduce__ API
+ 
+     There are several APIs that a class can use to control pickling.
+     Perhaps the most popular of these are __getstate__ and
+     __setstate__; but the most powerful one is __reduce__.  (There's
+     also __getinitargs__, and we're adding __getnewargs__ below.)
+ 
+     There are two ways to provide __reduce__ functionality: a class
+     can implement a __reduce__ method, or a reduce function can be
+     declared in copy_reg (copy_reg.dispatch_table maps classes to
+     functions).  The return values are interpreted exactly the same,
+     though, and we'll refer to these collectively as __reduce__.
+ 
+     __reduce__ must return either a string or a tuple.  If it returns
+     a string, this is an object whose state is not to be pickled, but
+     instead a reference to an equivalent object referenced by name.
+     Surprisingly, the string returned by __reduce__ should be the
+     object's local name (relative to its module); the pickle module
+     searches the module namespace to determine the object's module.
+ 
+     The rest of this section is concerned with the tuple returned by
+     __reduce__.  It is a variable length tuple.  Only the first two
+     items (function and arguments) are required.  The remaining items
+     may be None or left off from the end.  The last two items are new
+     in this PEP.  The items are, in order:
+ 
+     function     A callable object (not necessarily a function) called
+                  to create the initial version of the object; state may
+                  be added to the object later to fully reconstruct the
+                  pickled state.  This function must itself be
+                  picklable.
+ 
+     arguments    A tuple giving the argument list for the function.
+                  As a special case, designed for Zope 2's
+                  ExtensionClass, this may be None; in that case,
+                  function should be a class or type, and
+                  function.__basicnew__() is called to create the
+                  initial version of the object.  This exception is
+                  deprecated.
+ 
+     state        Additional state.  If this is not None, the state is
+                  pickled, and obj.__setstate__(state) will called when
+                  unpickling.  If no __setstate__ method is defined, a
+                  default implementation is provided, which assumes
+                  that state is a dictionary mapping instance variable
+                  names to their values, and calls
+                  obj.__dict__.update(state) or "for k, v in
+                  state.items(): obj[k] = v", if update() call fails.
+ 
+     listitems    New in this PEP.  If this is not None, it should be
+                  an iterator (not a sequence!) yielding successive
+                  list items.  These list items will be pickled, and
+                  appended to the object using either obj.append(item)
+                  or obj.extend(list_of_items).  This is primarily used
+                  for list subclasses, but may be used by other classes
+                  as long as they have append() and extend() methods
+                  with the appropriate signature.  (Whether append() or
+                  extend() is used depend on which pickle protocol
+                  version is used as well as the number of items to
+                  append, so both must be supported.)
+ 
+     dictitems    New in this PEP.  If this is not None, it should be
+                  an iterator (not a sequence!) yielding successive
+                  dictionary items, which should be tuples of the form
+                  (key, value).  These items will be pickled, and
+                  stored to the object using obj[key] = value.  This is
+                  primarily used for dict subclasses, but may be used
+                  by other classes as long as they implement
+                  __settitem__.
+ 
+     Note: in Python 2.2 and before, when using cPickle, state would be
+     pickled if present even if it is None; the only safe way to avoid
+     the __setstate__ call was to return a two-tuple from __reduce__.
+     (But pickle.py would not pickle state if it was None.)  In Python
+     2.3, __setstate__ will never be called when __reduce__ returns a
+     state with value None.
+ 
+ 
  Copyright