[Python-checkins] python/nondist/peps pep-0307.txt,1.29,1.30

[gvanrossum@users.sourceforge.net]

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

Modified Files:
	pep-0307.txt 
Log Message:
Document __reduce_ex__.


Index: pep-0307.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0307.txt,v
retrieving revision 1.29
retrieving revision 1.30
diff -C2 -d -r1.29 -r1.30
*** pep-0307.txt	13 Feb 2003 16:08:06 -0000	1.29
--- pep-0307.txt	19 Feb 2003 01:59:59 -0000	1.30
***************
*** 142,157 ****
      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__.
  
!     IMPORTANT:  while a classic class can implement a __reduce__()
!     method, pickling its instances ignores the method, so that a classic
!     class cannot provide __reduce__ functionality in the sense intended
!     here.  (The copy_reg dispatch table is not consulted for classic
!     classes either.)  A classic class must use __getinitargs__ and/or
!     __gestate__ to customize pickling.  These are described below.
  
      __reduce__ must return either a string or a tuple.  If it returns
--- 142,158 ----
      also __getinitargs__, and we're adding __getnewargs__ below.)
  
!     There are several ways to provide __reduce__ functionality: a
!     class can implement a __reduce__ method or a __reduce_ex__ method
!     (see next section), 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__.
  
!     IMPORTANT: pickling of classic class instances does not look for a
!     __reduce__ or __reduce_ex__ method or a reduce function in the
!     copy_reg dispatch table, so that a classic class cannot provide
!     __reduce__ functionality in the sense intended here.  A classic
!     class must use __getinitargs__ and/or __gestate__ to customize
!     pickling.  These are described below.
  
      __reduce__ must return either a string or a tuple.  If it returns
***************
*** 246,249 ****
--- 247,266 ----
  
  
+ The __reduce_ex__ API
+ 
+     It is sometimes useful to know the protocol version when
+     implementing __reduce__.  This can be done by implementing a
+     method named __reduce_ex__ instead of __reduce__.  __reduce_ex__,
+     when it exists, is called in preference over __reduce__ (you may
+     still provide __reduce__ for backwards compatibility).  The
+     __reduce_ex__ method will be called with a single integer
+     argument, the protocol version.
+ 
+     The 'object' class implements both __reduce__ and __reduce_ex__;
+     however, if a subclass overrides __reduce__ but not __reduce_ex__,
+     the __reduce_ex__ implementation detects this and calls
+     __reduce__.
+ 
+ 
  Customizing pickling absent a __reduce__ implementation
  
***************
*** 662,665 ****
--- 679,685 ----
  
      In Python 2.3, several changes are made to the copy module:
+ 
+     - __reduce_ex__ is supported (and always called with 2 as the
+       protocol version argument).
  
      - The four- and five-argument return values of __reduce__ are