[Python-Dev] pickle.dump(..) interface change ... documentation

[Christian Stork]

On Wed, Feb 04, 2004 at 02:15:06PM -0600, Skip Montanaro wrote:
>     Chris> I just ran across something that looks like a very unfortunate interface
>     Chris> change in the pickle module:

Actually, I should have reworded that after I realized that it's only a
little problem with the docs.  The interface change is not unfortunate
(indeed it is fortunate as Guido stated ;-) but tricky.  That's why I
ask for a little explanation in the docs for the "type
re-interpretation", ie from bool to int.

>     Chris> Python 2.2:  dump(object, file[, bin])
>     Chris> Python 2.3:  dump(object, file[, protocol[, bin]])
> 
> From the docs:
> 
>     Changed in version 2.3: The protocol parameter was added. The bin
>     parameter is deprecated and only provided for backwards compatibility.
>     You should use the protocol parameter instead.

This is what I've been referring to.  (I should have quoted it.)

> I don't know if that's sufficient for your needs, but it does suggest that
> dump() calls which used the bin parameter should be inspected.

Well, actually there doesn't seem to be a need for reinspection unless
one wants to use the new protocol (ie protocol 2).  That's my whole
point.  It's not clear from the method signature that there is no
incompatble interface change...  [Again looking thru the docs...]
Actually, it's not so bad, 3.14.2 of the LibRef kind of explains it all,
and... [looking at pickle.py] I see that bin and protocol args are
perfectly checked for sensibility. :-)

Quintessence:  Maybe change the description of dump in the "3.14.3
Usage" to something saying 

"Changed in version 2.3: The protocol parameter was added _but_maintains
backward_compatibility_for_positional_arguments_of_the_former_bin
parameter_. The bin parameter is deprecated and..."

This prevents posts like this ;-) and is a help to the lazy ones who
don't want to reread the whole subsection.

Anyway, enough noise,
Chris

-- 
Chris Stork   <>  Support eff.org!  <>   http://www.ics.uci.edu/~cstork/
OpenPGP fingerprint:  B08B 602C C806 C492 D069  021E 41F3 8C8D 50F9 CA2F