mirror of https://github.com/python/cpython
Give the pickle special methods a signature.
This commit is contained in:
Georg Brandl
parent
4e47680060
commit
66ef83bd9d
|
|
@ -396,6 +396,8 @@ conversions can be made by the class's :meth:`__setstate__` method.
|
||||||
The pickle protocol
|
The pickle protocol
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
|
.. currentmodule:: None
|
||||||
|
|
||||||
This section describes the "pickling protocol" that defines the interface
|
This section describes the "pickling protocol" that defines the interface
|
||||||
between the pickler/unpickler and the objects that are being serialized. This
|
between the pickler/unpickler and the objects that are being serialized. This
|
||||||
protocol provides a standard way for you to define, customize, and control how
|
protocol provides a standard way for you to define, customize, and control how
|
||||||
|
|
@ -410,129 +412,126 @@ environment slightly safer from untrusted pickle data streams; see section
|
||||||
Pickling and unpickling normal class instances
|
Pickling and unpickling normal class instances
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
.. index::
|
.. method:: object.__getinitargs__()
|
||||||
single: __getinitargs__() (copy protocol)
|
|
||||||
single: __init__() (instance constructor)
|
When a pickled class instance is unpickled, its :meth:`__init__` method is
|
||||||
|
normally *not* invoked. If it is desirable that the :meth:`__init__` method
|
||||||
|
be called on unpickling, an old-style class can define a method
|
||||||
|
:meth:`__getinitargs__`, which should return a *tuple* containing the
|
||||||
|
arguments to be passed to the class constructor (:meth:`__init__` for
|
||||||
|
example). The :meth:`__getinitargs__` method is called at pickle time; the
|
||||||
|
tuple it returns is incorporated in the pickle for the instance.
|
||||||
|
|
||||||
When a pickled class instance is unpickled, its :meth:`__init__` method is
|
.. method:: object.__getnewargs__()
|
||||||
normally *not* invoked. If it is desirable that the :meth:`__init__` method be
|
|
||||||
called on unpickling, an old-style class can define a method
|
|
||||||
:meth:`__getinitargs__`, which should return a *tuple* containing the arguments
|
|
||||||
to be passed to the class constructor (:meth:`__init__` for example). The
|
|
||||||
:meth:`__getinitargs__` method is called at pickle time; the tuple it returns is
|
|
||||||
incorporated in the pickle for the instance.
|
|
||||||
|
|
||||||
.. index:: single: __getnewargs__() (copy protocol)
|
New-style types can provide a :meth:`__getnewargs__` method that is used for
|
||||||
|
protocol 2. Implementing this method is needed if the type establishes some
|
||||||
|
internal invariants when the instance is created, or if the memory allocation
|
||||||
|
is affected by the values passed to the :meth:`__new__` method for the type
|
||||||
|
(as it is for tuples and strings). Instances of a :term:`new-style class`
|
||||||
|
``C`` are created using ::
|
||||||
|
|
||||||
|
obj = C.__new__(C, *args)
|
||||||
|
|
||||||
|
where *args* is the result of calling :meth:`__getnewargs__` on the original
|
||||||
|
object; if there is no :meth:`__getnewargs__`, an empty tuple is assumed.
|
||||||
|
|
||||||
New-style types can provide a :meth:`__getnewargs__` method that is used for
|
.. method:: object.__getstate__()
|
||||||
protocol 2. Implementing this method is needed if the type establishes some
|
|
||||||
internal invariants when the instance is created, or if the memory allocation is
|
Classes can further influence how their instances are pickled; if the class
|
||||||
affected by the values passed to the :meth:`__new__` method for the type (as it
|
defines the method :meth:`__getstate__`, it is called and the return state is
|
||||||
is for tuples and strings). Instances of a :term:`new-style class` :class:`C`
|
pickled as the contents for the instance, instead of the contents of the
|
||||||
are created using ::
|
instance's dictionary. If there is no :meth:`__getstate__` method, the
|
||||||
|
instance's :attr:`__dict__` is pickled.
|
||||||
|
|
||||||
obj = C.__new__(C, *args)
|
.. method:: object.__setstate__()
|
||||||
|
|
||||||
|
Upon unpickling, if the class also defines the method :meth:`__setstate__`,
|
||||||
where *args* is the result of calling :meth:`__getnewargs__` on the original
|
it is called with the unpickled state. [#]_ If there is no
|
||||||
object; if there is no :meth:`__getnewargs__`, an empty tuple is assumed.
|
:meth:`__setstate__` method, the pickled state must be a dictionary and its
|
||||||
|
items are assigned to the new instance's dictionary. If a class defines both
|
||||||
.. index::
|
:meth:`__getstate__` and :meth:`__setstate__`, the state object needn't be a
|
||||||
single: __getstate__() (copy protocol)
|
dictionary and these methods can do what they want. [#]_
|
||||||
single: __setstate__() (copy protocol)
|
|
||||||
single: __dict__ (instance attribute)
|
.. warning::
|
||||||
|
|
||||||
Classes can further influence how their instances are pickled; if the class
|
For :term:`new-style class`\es, if :meth:`__getstate__` returns a false
|
||||||
defines the method :meth:`__getstate__`, it is called and the return state is
|
value, the :meth:`__setstate__` method will not be called.
|
||||||
pickled as the contents for the instance, instead of the contents of the
|
|
||||||
instance's dictionary. If there is no :meth:`__getstate__` method, the
|
|
||||||
instance's :attr:`__dict__` is pickled.
|
|
||||||
|
|
||||||
Upon unpickling, if the class also defines the method :meth:`__setstate__`, it
|
|
||||||
is called with the unpickled state. [#]_ If there is no :meth:`__setstate__`
|
|
||||||
method, the pickled state must be a dictionary and its items are assigned to the
|
|
||||||
new instance's dictionary. If a class defines both :meth:`__getstate__` and
|
|
||||||
:meth:`__setstate__`, the state object needn't be a dictionary and these methods
|
|
||||||
can do what they want. [#]_
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
For :term:`new-style class`\es, if :meth:`__getstate__` returns a false
|
|
||||||
value, the :meth:`__setstate__` method will not be called.
|
|
||||||
|
|
||||||
|
|
||||||
Pickling and unpickling extension types
|
Pickling and unpickling extension types
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
.. index::
|
.. method:: object.__reduce__()
|
||||||
single: __reduce__() (pickle protocol)
|
|
||||||
single: __reduce_ex__() (pickle protocol)
|
When the :class:`Pickler` encounters an object of a type it knows nothing
|
||||||
single: __safe_for_unpickling__ (pickle protocol)
|
about --- such as an extension type --- it looks in two places for a hint of
|
||||||
|
how to pickle it. One alternative is for the object to implement a
|
||||||
|
:meth:`__reduce__` method. If provided, at pickling time :meth:`__reduce__`
|
||||||
|
will be called with no arguments, and it must return either a string or a
|
||||||
|
tuple.
|
||||||
|
|
||||||
When the :class:`Pickler` encounters an object of a type it knows nothing about
|
If a string is returned, it names a global variable whose contents are
|
||||||
--- such as an extension type --- it looks in two places for a hint of how to
|
pickled as normal. The string returned by :meth:`__reduce__` should be the
|
||||||
pickle it. One alternative is for the object to implement a :meth:`__reduce__`
|
object's local name relative to its module; the pickle module searches the
|
||||||
method. If provided, at pickling time :meth:`__reduce__` will be called with no
|
module namespace to determine the object's module.
|
||||||
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
|
When a tuple is returned, it must be between two and five elements long.
|
||||||
as normal. The string returned by :meth:`__reduce__` should be the object's
|
Optional elements can either be omitted, or ``None`` can be provided as their
|
||||||
local name relative to its module; the pickle module searches the module
|
value. The contents of this tuple are pickled as normal and used to
|
||||||
namespace to determine the object's module.
|
reconstruct the object at unpickling time. The semantics of each element
|
||||||
|
are:
|
||||||
|
|
||||||
When a tuple is returned, it must be between two and five elements long.
|
* A callable object that will be called to create the initial version of the
|
||||||
Optional elements can either be omitted, or ``None`` can be provided as their
|
object. The next element of the tuple will provide arguments for this
|
||||||
value. The contents of this tuple are pickled as normal and used to
|
callable, and later elements provide additional state information that will
|
||||||
reconstruct the object at unpickling time. The semantics of each element are:
|
subsequently be used to fully reconstruct the pickled data.
|
||||||
|
|
||||||
* A callable object that will be called to create the initial version of the
|
In the unpickling environment this object must be either a class, a
|
||||||
object. The next element of the tuple will provide arguments for this callable,
|
callable registered as a "safe constructor" (see below), or it must have an
|
||||||
and later elements provide additional state information that will subsequently
|
attribute :attr:`__safe_for_unpickling__` with a true value. Otherwise, an
|
||||||
be used to fully reconstruct the pickled data.
|
:exc:`UnpicklingError` will be raised in the unpickling 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
|
* A tuple of arguments for the callable object.
|
||||||
registered as a "safe constructor" (see below), or it must have an attribute
|
|
||||||
:attr:`__safe_for_unpickling__` with a true value. Otherwise, an
|
|
||||||
:exc:`UnpicklingError` will be raised in the unpickling environment. Note that
|
|
||||||
as usual, the callable itself is pickled by name.
|
|
||||||
|
|
||||||
* A tuple of arguments for the callable object.
|
.. versionchanged:: 2.5
|
||||||
|
Formerly, this argument could also be ``None``.
|
||||||
|
|
||||||
.. versionchanged:: 2.5
|
* Optionally, the object's state, which will be passed to the object's
|
||||||
Formerly, this argument could also be ``None``.
|
:meth:`__setstate__` method as described in section :ref:`pickle-inst`. If
|
||||||
|
the object has no :meth:`__setstate__` method, then, as above, the value
|
||||||
|
must be a dictionary and it will be added to the object's :attr:`__dict__`.
|
||||||
|
|
||||||
* Optionally, the object's state, which will be passed to the object's
|
* Optionally, an iterator (and not a sequence) yielding successive list
|
||||||
:meth:`__setstate__` method as described in section :ref:`pickle-inst`. If the
|
items. These list items will be pickled, and appended to the object using
|
||||||
object has no :meth:`__setstate__` method, then, as above, the value must be a
|
either ``obj.append(item)`` or ``obj.extend(list_of_items)``. This is
|
||||||
dictionary and it will be added to the object's :attr:`__dict__`.
|
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, an iterator (and not a sequence) yielding successive list items.
|
* Optionally, an iterator (not a sequence) yielding successive dictionary
|
||||||
These list items will be pickled, and appended to the object using either
|
items, which should be tuples of the form ``(key, value)``. These items
|
||||||
``obj.append(item)`` or ``obj.extend(list_of_items)``. This is primarily used
|
will be pickled and stored to the object using ``obj[key] = value``. This
|
||||||
for list subclasses, but may be used by other classes as long as they have
|
is primarily used for dictionary subclasses, but may be used by other
|
||||||
:meth:`append` and :meth:`extend` methods with the appropriate signature.
|
classes as long as they implement :meth:`__setitem__`.
|
||||||
(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, an iterator (not a sequence) yielding successive dictionary items,
|
.. method:: object.__reduce_ex__(protocol)
|
||||||
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 dictionary subclasses, but may be used by other classes as long as they
|
|
||||||
implement :meth:`__setitem__`.
|
|
||||||
|
|
||||||
It is sometimes useful to know the protocol version when implementing
|
It is sometimes useful to know the protocol version when implementing
|
||||||
:meth:`__reduce__`. This can be done by implementing a method named
|
:meth:`__reduce__`. This can be done by implementing a method named
|
||||||
:meth:`__reduce_ex__` instead of :meth:`__reduce__`. :meth:`__reduce_ex__`, when
|
:meth:`__reduce_ex__` instead of :meth:`__reduce__`. :meth:`__reduce_ex__`,
|
||||||
it exists, is called in preference over :meth:`__reduce__` (you may still
|
when it exists, is called in preference over :meth:`__reduce__` (you may
|
||||||
provide :meth:`__reduce__` for backwards compatibility). The
|
still provide :meth:`__reduce__` for backwards compatibility). The
|
||||||
:meth:`__reduce_ex__` method will be called with a single integer argument, the
|
:meth:`__reduce_ex__` method will be called with a single integer argument,
|
||||||
protocol version.
|
the protocol version.
|
||||||
|
|
||||||
The :class:`object` class implements both :meth:`__reduce__` and
|
The :class:`object` class implements both :meth:`__reduce__` and
|
||||||
:meth:`__reduce_ex__`; however, if a subclass overrides :meth:`__reduce__` but
|
:meth:`__reduce_ex__`; however, if a subclass overrides :meth:`__reduce__`
|
||||||
not :meth:`__reduce_ex__`, the :meth:`__reduce_ex__` implementation detects this
|
but not :meth:`__reduce_ex__`, the :meth:`__reduce_ex__` implementation
|
||||||
and calls :meth:`__reduce__`.
|
detects this and calls :meth:`__reduce__`.
|
||||||
|
|
||||||
An alternative to implementing a :meth:`__reduce__` method on the object to be
|
An alternative to implementing a :meth:`__reduce__` method on the object to be
|
||||||
pickled, is to register the callable with the :mod:`copy_reg` module. This
|
pickled, is to register the callable with the :mod:`copy_reg` module. This
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue