Clarified the distinction between pickling time and unpickling time

where that seemed to help, and made explicit where "the object" came
from originally in the descriptions of the optional __reduce__ tuple
elements.
This commit is contained in:
Tim Peters 2003-02-10 22:13:34 +00:00
parent ae56c6a44c
commit 586a9c30cc
1 changed files with 18 additions and 7 deletions

View File

@ -181,15 +181,26 @@ Extended __reduce__ API
initial version of the object. This exception is
deprecated.
Unpickling invokes function(*arguments) to create an initial object,
called obj below. If the remaining items are left off, that's the end
of unpickling and obj is the result. Else obj is modified at
unpickling time by each item specified, as follows.
state Optional.
Additional state. If this is not None, the state is
pickled, and obj.__setstate__(state) will be 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.
variable names to their values. The default
implementation calls
obj.__dict__.update(state)
or, if the update() call fails,
for k, v in state.items():
obj[k] = v
listitems Optional, and new in this PEP.
If this is not None, it should be an iterator (not a
@ -203,7 +214,7 @@ Extended __reduce__ API
pickle protocol version is used as well as the number
of items to append, so both must be supported.)
dictitems Optionals, and new in this PEP.
dictitems Optional, and 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
@ -216,15 +227,15 @@ Extended __reduce__ API
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.
2.3, __setstate__ will never be called at unpickling time when
__reduce__ returns a state with value None at pickling time.
A __reduce__ implementation that needs to work both under Python
2.2 and under Python 2.3 could check the variable
pickle.format_version to determine whether to use the listitems
and dictitems features. If this value is >= "2.0" then they are
supported. If not, any list or dict items should be incorporated
somehow in the 'state' return value; the __setstate__ method
somehow in the 'state' return value, and the __setstate__ method
should be prepared to accept list or dict items as part of the
state (how this is done is up to the application).