Document extended __reduce__ API.
This commit is contained in:
parent
57d97aaec1
commit
628e37cde1
78
pep-0307.txt
78
pep-0307.txt
|
@ -106,6 +106,84 @@ Security issues
|
||||||
unauthenticated source ***
|
unauthenticated source ***
|
||||||
|
|
||||||
|
|
||||||
|
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
|
Copyright
|
||||||
|
|
||||||
This document has been placed in the public domain.
|
This document has been placed in the public domain.
|
||||||
|
|
Loading…
Reference in New Issue