Port changes to pickle docs apparently lost in py3k.
This commit is contained in:
Georg Brandl
parent
8527126f85
commit
c8148265dc
|
|
@ -427,33 +427,38 @@ implementation of this behaviour::
|
|||
obj.__dict__.update(attributes)
|
||||
return obj
|
||||
|
||||
.. index:: single: __getnewargs__() (copy protocol)
|
||||
|
||||
Classes can alter the default behaviour by providing one or several special
|
||||
methods. In protocol 2 and newer, classes that implements the
|
||||
:meth:`__getnewargs__` method can dictate the values passed to the
|
||||
:meth:`__new__` method upon unpickling. This is often needed for classes
|
||||
whose :meth:`__new__` method requires arguments.
|
||||
methods:
|
||||
|
||||
.. index:: single: __getstate__() (copy protocol)
|
||||
.. method:: object.__getnewargs__()
|
||||
|
||||
Classes can further influence how their instances are pickled; if the class
|
||||
defines the method :meth:`__getstate__`, it is called and the returned object is
|
||||
pickled as the contents for the instance, instead of the contents of the
|
||||
instance's dictionary. If the :meth:`__getstate__` method is absent, the
|
||||
instance's :attr:`__dict__` is pickled as usual.
|
||||
In protocol 2 and newer, classes that implements the :meth:`__getnewargs__`
|
||||
method can dictate the values passed to the :meth:`__new__` method upon
|
||||
unpickling. This is often needed for classes whose :meth:`__new__` method
|
||||
requires arguments.
|
||||
|
||||
.. index:: single: __setstate__() (copy protocol)
|
||||
|
||||
Upon unpickling, if the class defines :meth:`__setstate__`, it is called with
|
||||
the unpickled state. In that case, there is no requirement for the state object
|
||||
to be a dictionary. Otherwise, the pickled state must be a dictionary and its
|
||||
items are assigned to the new instance's dictionary.
|
||||
.. method:: object.__getstate__()
|
||||
|
||||
.. note::
|
||||
Classes can further influence how their instances are pickled; if the class
|
||||
defines the method :meth:`__getstate__`, it is called and the returned object
|
||||
is pickled as the contents for the instance, instead of the contents of the
|
||||
instance's dictionary. If the :meth:`__getstate__` method is absent, the
|
||||
instance's :attr:`__dict__` is pickled as usual.
|
||||
|
||||
|
||||
.. method:: object.__setstate__(state)
|
||||
|
||||
Upon unpickling, if the class defines :meth:`__setstate__`, it is called with
|
||||
the unpickled state. In that case, there is no requirement for the state
|
||||
object to be a dictionary. Otherwise, the pickled state must be a dictionary
|
||||
and its items are assigned to the new instance's dictionary.
|
||||
|
||||
.. note::
|
||||
|
||||
If :meth:`__getstate__` returns a false value, the :meth:`__setstate__`
|
||||
method will not be called upon unpickling.
|
||||
|
||||
If :meth:`__getstate__` returns a false value, the :meth:`__setstate__`
|
||||
method will not be called.
|
||||
|
||||
Refer to the section :ref:`pickle-state` for more information about how to use
|
||||
the methods :meth:`__getstate__` and :meth:`__setstate__`.
|
||||
|
|
@ -462,14 +467,12 @@ the methods :meth:`__getstate__` and :meth:`__setstate__`.
|
|||
|
||||
At unpickling time, some methods like :meth:`__getattr__`,
|
||||
:meth:`__getattribute__`, or :meth:`__setattr__` may be called upon the
|
||||
instance. In case those methods rely on some internal invariant being
|
||||
true, the type should implement either :meth:`__getinitargs__` or
|
||||
:meth:`__getnewargs__` to establish such an invariant; otherwise, neither
|
||||
:meth:`__new__` nor :meth:`__init__` will be called.
|
||||
instance. In case those methods rely on some internal invariant being true,
|
||||
the type should implement :meth:`__getnewargs__` to establish such an
|
||||
invariant; otherwise, neither :meth:`__new__` nor :meth:`__init__` will be
|
||||
called.
|
||||
|
||||
.. index::
|
||||
pair: copy; protocol
|
||||
single: __reduce__() (copy protocol)
|
||||
.. index:: pair: copy; protocol
|
||||
|
||||
As we shall see, pickle does not use directly the methods described above. In
|
||||
fact, these methods are part of the copy protocol which implements the
|
||||
|
|
@ -480,58 +483,61 @@ objects. [#]_
|
|||
Although powerful, implementing :meth:`__reduce__` directly in your classes is
|
||||
error prone. For this reason, class designers should use the high-level
|
||||
interface (i.e., :meth:`__getnewargs__`, :meth:`__getstate__` and
|
||||
:meth:`__setstate__`) whenever possible. We will show, however, cases where using
|
||||
:meth:`__reduce__` is the only option or leads to more efficient pickling or
|
||||
both.
|
||||
:meth:`__setstate__`) whenever possible. We will show, however, cases where
|
||||
using :meth:`__reduce__` is the only option or leads to more efficient pickling
|
||||
or both.
|
||||
|
||||
The interface is currently defined as follows. The :meth:`__reduce__` method
|
||||
takes no argument and shall return either a string or preferably a tuple (the
|
||||
returned object is often referred to as the "reduce value").
|
||||
.. method:: object.__reduce__()
|
||||
|
||||
If a string is returned, the string should be interpreted as the name of a
|
||||
global variable. It should be the object's local name relative to its module;
|
||||
the pickle module searches the module namespace to determine the object's
|
||||
module. This behaviour is typically useful for singletons.
|
||||
The interface is currently defined as follows. The :meth:`__reduce__` method
|
||||
takes no argument and shall return either a string or preferably a tuple (the
|
||||
returned object is often referred to as the "reduce value").
|
||||
|
||||
When a tuple is returned, it must be between two and five items long. Optional
|
||||
items can either be omitted, or ``None`` can be provided as their value. The
|
||||
semantics of each item are in order:
|
||||
If a string is returned, the string should be interpreted as the name of a
|
||||
global variable. It should be the object's local name relative to its
|
||||
module; the pickle module searches the module namespace to determine the
|
||||
object's module. This behaviour is typically useful for singletons.
|
||||
|
||||
.. XXX Mention __newobj__ special-case?
|
||||
When a tuple is returned, it must be between two and five items long.
|
||||
Optional items can either be omitted, or ``None`` can be provided as their
|
||||
value. The semantics of each item are in order:
|
||||
|
||||
* A callable object that will be called to create the initial version of the
|
||||
object.
|
||||
.. XXX Mention __newobj__ special-case?
|
||||
|
||||
* A tuple of arguments for the callable object. An empty tuple must be given if
|
||||
the callable does not accept any argument.
|
||||
* A callable object that will be called to create the initial version of the
|
||||
object.
|
||||
|
||||
* Optionally, the object's state, which will be passed to the object's
|
||||
:meth:`__setstate__` method as previously described. If the object has no
|
||||
such method then, the value must be a dictionary and it will be added to the
|
||||
object's :attr:`__dict__` attribute.
|
||||
* A tuple of arguments for the callable object. An empty tuple must be given
|
||||
if the callable does not accept any argument.
|
||||
|
||||
* Optionally, an iterator (and not a sequence) yielding successive items. These
|
||||
items will be appended to the object either using ``obj.append(item)`` or, in
|
||||
batch, using ``obj.extend(list_of_items)``. This is primarily used for list
|
||||
subclasses, but may be used by other classes as long as they have
|
||||
:meth:`append` and :meth:`extend` methods with the appropriate signature.
|
||||
(Whether :meth:`append` or :meth:`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.)
|
||||
* Optionally, the object's state, which will be passed to the object's
|
||||
:meth:`__setstate__` method as previously described. If the object has no
|
||||
such method then, the value must be a dictionary and it will be added to
|
||||
the object's :attr:`__dict__` attribute.
|
||||
|
||||
* Optionally, an iterator (not a sequence) yielding successive key-value pairs.
|
||||
These items will be stored to the object using ``obj[key] = value``. This is
|
||||
primarily used for dictionary subclasses, but may be used by other classes as
|
||||
long as they implement :meth:`__setitem__`.
|
||||
* Optionally, an iterator (and not a sequence) yielding successive items.
|
||||
These items will be appended to the object either using
|
||||
``obj.append(item)`` or, in batch, using ``obj.extend(list_of_items)``.
|
||||
This is primarily used for list subclasses, but may be used by other
|
||||
classes as long as they have :meth:`append` and :meth:`extend` methods with
|
||||
the appropriate signature. (Whether :meth:`append` or :meth:`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.)
|
||||
|
||||
.. index:: single: __reduce_ex__() (copy protocol)
|
||||
* Optionally, an iterator (not a sequence) yielding successive key-value
|
||||
pairs. These items will be stored to the object using ``obj[key] =
|
||||
value``. This is primarily used for dictionary subclasses, but may be used
|
||||
by other classes as long as they implement :meth:`__setitem__`.
|
||||
|
||||
Alternatively, a :meth:`__reduce_ex__` method may be defined. The only
|
||||
difference is this method should take a single integer argument, the protocol
|
||||
version. When defined, pickle will prefer it over the :meth:`__reduce__`
|
||||
method. In addition, :meth:`__reduce__` automatically becomes a synonym for the
|
||||
extended version. The main use for this method is to provide
|
||||
backwards-compatible reduce values for older Python releases.
|
||||
|
||||
.. method:: object.__reduce_ex__(protocol)
|
||||
|
||||
Alternatively, a :meth:`__reduce_ex__` method may be defined. The only
|
||||
difference is this method should take a single integer argument, the protocol
|
||||
version. When defined, pickle will prefer it over the :meth:`__reduce__`
|
||||
method. In addition, :meth:`__reduce__` automatically becomes a synonym for
|
||||
the extended version. The main use for this method is to provide
|
||||
backwards-compatible reduce values for older Python releases.
|
||||
|
||||
.. _pickle-persistent:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue