Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

[Bug #984952] Include some material from PEP 307

This commit is contained in:
Andrew M. Kuchling 2004-08-07 15:49:24 +00:00
parent 2b3feec58f
commit 14d535c3d4
1 changed files with 35 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
Doc/lib/libpickle.tex
View File

@ -515,8 +515,8 @@ time \method{__reduce__()} will be called with no arguments, and it
must return either a string or a tuple.
If a string is returned, it names a global variable whose contents are
pickled as normal. When a tuple is returned, it must be of length two
or three, with the following semantics:
pickled as normal. When a tuple is returned, it must be between two
and five elements long, with the following semantics:
\begin{itemize}
@ -530,7 +530,6 @@ or three, with the following semantics:
\item A tuple of arguments for the callable object, or \code{None}.
\deprecated{2.3}{Use the tuple of arguments instead}
\item Optionally, the object's state, which will be passed to
the object's \method{__setstate__()} method as described in
section~\ref{pickle-inst}. If the object has no
@ -538,6 +537,23 @@ or three, with the following semantics:
be a dictionary and it will be added to the object's
\member{__dict__}.
\item Optionally, an iterator (and not a sequence) yielding successive
list items. These list items will be pickled, and appended to the
object using either \code{obj.append(\var{item})} or
\code{obj.extend(\var{list_of_items})}. This is primarily used for
list subclasses, but may be used by other classes as long as they have
\method{append()} and \method{extend()} methods with the appropriate
signature. (Whether \method{append()} or \method{extend()} is used
depends on which pickle protocol version is used as well as the number
of items to append, so both must be supported.)
\item Optionally, an iterator (not a sequence)
yielding successive dictionary items, which should be tuples of the
form \code{(\var{key}, \var{value})}. These items will be pickled
and stored to the object using \code{obj[\var{key}] = \var{value}}.
This is primarily used for dictionary subclasses, but may be used by
other classes as long as they implement \method{__setitem__}.
\end{itemize}
Upon unpickling, the callable will be called (provided that it meets
@ -559,7 +575,22 @@ 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.
It is sometimes useful to know the protocol version when implementing
\method{__reduce__}. This can be done by implementing a method named
\method{__reduce_ex__} instead of \method{__reduce__}.
\method{__reduce_ex__}, when it exists, is called in preference over
\method{__reduce__} (you may still provide \method{__reduce__} for
backwards compatibility). The \method{__reduce_ex__} method will be
called with a single integer argument, the protocol version.
The \class{object} class implements both \method{__reduce__} and
\method{__reduce_ex__}; however, if a subclass overrides
\method{__reduce__} but not \method{__reduce_ex__}, the
\method{__reduce_ex__} implementation detects this and calls
\method{__reduce__}.
\subsubsection{Pickling and unpickling external objects}