Commit cbbee6fe authored by Andrew M. Kuchling's avatar Andrew M. Kuchling

[Bug #984952] Include more material from PEP 307.

I haven't tried to include all the material on old-style classes using protocols 0,1.  The details are lengthy; someone who knows
more about the pickle module should decide if they're important enough
to be in the docs or not.
parent 8896bf56
...@@ -515,21 +515,36 @@ time \method{__reduce__()} will be called with no arguments, and it ...@@ -515,21 +515,36 @@ time \method{__reduce__()} will be called with no arguments, and it
must return either a string or a tuple. must return either a string or a tuple.
If a string is returned, it names a global variable whose contents are If a string is returned, it names a global variable whose contents are
pickled as normal. When a tuple is returned, it must be between two pickled as normal. The string returned by \method{__reduce__} should
and five elements long, with the following semantics: be the object's local name relative to its module; the pickle module
searches the module namespace to determine the object's module.
When a tuple is returned, it must be between two and five elements
long. Optional elements can either be omitted, or \code{None} can be provided
as their value. The semantics of each element are:
\begin{itemize} \begin{itemize}
\item A callable object, which in the unpickling environment must be \item A callable object that will be called to create the initial
either a class, a callable registered as a ``safe constructor'' version of the object. The next element of the tuple will provide
(see below), or it must have an attribute arguments for this callable, and later elements provide additional
\member{__safe_for_unpickling__} with a true value. Otherwise, state information that will subsequently be used to fully reconstruct
an \exception{UnpicklingError} will be raised in the unpickling the pickled date.
environment. Note that as usual, the callable itself is pickled
by name. In the unpickling environment this object must be either a class, a
callable registered as a ``safe constructor'' (see below), or it must
have an attribute \member{__safe_for_unpickling__} with a true value.
Otherwise, an \exception{UnpicklingError} will be raised in the
unpickling environment. Note that as usual, the callable itself is
pickled by name.
\item A tuple of arguments for the callable object, or \code{None}. \item A tuple of arguments for the callable object, or \code{None}.
\deprecated{2.3}{Use the tuple of arguments instead} \deprecated{2.3}{If this item is \code{None}, then instead of calling
the callable directly, its \method{__basicnew__()} method is called
without arguments; this method should also return the unpickled
object. Providing \code{None} is deprecated, however; return a
tuple of arguments instead.}
\item Optionally, the object's state, which will be passed to \item Optionally, the object's state, which will be passed to
the object's \method{__setstate__()} method as described in the object's \method{__setstate__()} method as described in
section~\ref{pickle-inst}. If the object has no section~\ref{pickle-inst}. If the object has no
...@@ -556,26 +571,6 @@ other classes as long as they implement \method{__setitem__}. ...@@ -556,26 +571,6 @@ other classes as long as they implement \method{__setitem__}.
\end{itemize} \end{itemize}
Upon unpickling, the callable will be called (provided that it meets
the above criteria), passing in the tuple of arguments; it should
return the unpickled object.
If the second item was \code{None}, then instead of calling the
callable directly, its \method{__basicnew__()} method is called
without arguments. It should also return the unpickled object.
\deprecated{2.3}{Use the tuple of arguments instead}
An alternative to implementing a \method{__reduce__()} method on the
object to be pickled, is to register the callable with the
\refmodule[copyreg]{copy_reg} module. This module provides a way
for programs to register ``reduction functions'' and constructors for
user-defined types. Reduction functions have the same semantics and
interface as the \method{__reduce__()} method described above, except
that they are called with a single argument, the object to be pickled.
The registered constructor is deemed a ``safe constructor'' for purposes
It is sometimes useful to know the protocol version when implementing It is sometimes useful to know the protocol version when implementing
\method{__reduce__}. This can be done by implementing a method named \method{__reduce__}. This can be done by implementing a method named
\method{__reduce_ex__} instead of \method{__reduce__}. \method{__reduce_ex__} instead of \method{__reduce__}.
...@@ -590,6 +585,16 @@ The \class{object} class implements both \method{__reduce__} and ...@@ -590,6 +585,16 @@ The \class{object} class implements both \method{__reduce__} and
\method{__reduce_ex__} implementation detects this and calls \method{__reduce_ex__} implementation detects this and calls
\method{__reduce__}. \method{__reduce__}.
An alternative to implementing a \method{__reduce__()} method on the
object to be pickled, is to register the callable with the
\refmodule[copyreg]{copy_reg} module. This module provides a way
for programs to register ``reduction functions'' and constructors for
user-defined types. Reduction functions have the same semantics and
interface as the \method{__reduce__()} method described above, except
that they are called with a single argument, the object to be pickled.
The registered constructor is deemed a ``safe constructor'' for purposes
of unpickling as described above.
\subsubsection{Pickling and unpickling external objects} \subsubsection{Pickling and unpickling external objects}
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment