[Python-checkins] r64702 - python/trunk/Doc/library/pickle.rst
georg.brandl
python-checkins at python.org
Fri Jul 4 19:22:53 CEST 2008
Author: georg.brandl
Date: Fri Jul 4 19:22:53 2008
New Revision: 64702
Log:
Give the pickle special methods a signature.
Modified:
python/trunk/Doc/library/pickle.rst
Modified: python/trunk/Doc/library/pickle.rst
==============================================================================
--- python/trunk/Doc/library/pickle.rst (original)
+++ python/trunk/Doc/library/pickle.rst Fri Jul 4 19:22:53 2008
@@ -396,6 +396,8 @@
The pickle protocol
-------------------
+.. currentmodule:: None
+
This section describes the "pickling protocol" that defines the interface
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
@@ -410,129 +412,126 @@
Pickling and unpickling normal class instances
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. index::
- 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.
-
-.. 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` :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.
-
-.. index::
- single: __getstate__() (copy protocol)
- single: __setstate__() (copy protocol)
- single: __dict__ (instance attribute)
-
-Classes can further influence how their instances are pickled; if the class
-defines the method :meth:`__getstate__`, it is called and the return state is
-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.
+.. method:: object.__getinitargs__()
+
+ 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.
+
+.. method:: object.__getnewargs__()
+
+ 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.
+
+.. method:: object.__getstate__()
+
+ Classes can further influence how their instances are pickled; if the class
+ defines the method :meth:`__getstate__`, it is called and the return state is
+ 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.
+
+.. method:: object.__setstate__()
+
+ 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. index::
- single: __reduce__() (pickle protocol)
- single: __reduce_ex__() (pickle protocol)
- single: __safe_for_unpickling__ (pickle protocol)
-
-When the :class:`Pickler` encounters an object of a type it knows nothing 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.
-
-If a string is returned, it names a global variable whose contents are pickled
-as normal. The string returned by :meth:`__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.
-
-When a tuple is returned, it must be between two and five elements long.
-Optional elements can either be omitted, or ``None`` can be provided as their
-value. The contents of this tuple are pickled as normal and used to
-reconstruct the object at unpickling time. The semantics of each element are:
-
-* A callable object that will be called to create the initial version of the
- object. The next element of the tuple will provide arguments for this callable,
- and later elements provide additional state information that will subsequently
- be used to fully reconstruct the pickled data.
-
- In the unpickling environment this object must be either a class, a callable
- 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``.
-
-* Optionally, the object's state, which will be passed to the object's
- :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, an iterator (and 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
- :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 (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 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
-:meth:`__reduce__`. This can be done by implementing a method named
-:meth:`__reduce_ex__` instead of :meth:`__reduce__`. :meth:`__reduce_ex__`, when
-it exists, is called in preference over :meth:`__reduce__` (you may still
-provide :meth:`__reduce__` for backwards compatibility). The
-:meth:`__reduce_ex__` method will be called with a single integer argument, the
-protocol version.
-
-The :class:`object` class implements both :meth:`__reduce__` and
-:meth:`__reduce_ex__`; however, if a subclass overrides :meth:`__reduce__` but
-not :meth:`__reduce_ex__`, the :meth:`__reduce_ex__` implementation detects this
-and calls :meth:`__reduce__`.
+.. method:: object.__reduce__()
+
+ When the :class:`Pickler` encounters an object of a type it knows nothing
+ 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.
+
+ If a string is returned, it names a global variable whose contents are
+ pickled as normal. The string returned by :meth:`__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.
+
+ When a tuple is returned, it must be between two and five elements long.
+ Optional elements can either be omitted, or ``None`` can be provided as their
+ value. The contents of this tuple are pickled as normal and used to
+ reconstruct the object at unpickling time. The semantics of each element
+ are:
+
+ * A callable object that will be called to create the initial version of the
+ object. The next element of the tuple will provide arguments for this
+ callable, and later elements provide additional state information that will
+ subsequently be used to fully reconstruct the pickled data.
+
+ In the unpickling environment this object must be either a class, a
+ callable 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``.
+
+ * Optionally, the object's state, which will be passed to the object's
+ :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, an iterator (and 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 :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 (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 dictionary subclasses, but may be used by other
+ classes as long as they implement :meth:`__setitem__`.
+
+.. method:: object.__reduce_ex__(protocol)
+
+ It is sometimes useful to know the protocol version when implementing
+ :meth:`__reduce__`. This can be done by implementing a method named
+ :meth:`__reduce_ex__` instead of :meth:`__reduce__`. :meth:`__reduce_ex__`,
+ when it exists, is called in preference over :meth:`__reduce__` (you may
+ still provide :meth:`__reduce__` for backwards compatibility). The
+ :meth:`__reduce_ex__` method will be called with a single integer argument,
+ the protocol version.
+
+ The :class:`object` class implements both :meth:`__reduce__` and
+ :meth:`__reduce_ex__`; however, if a subclass overrides :meth:`__reduce__`
+ but not :meth:`__reduce_ex__`, the :meth:`__reduce_ex__` implementation
+ detects this and calls :meth:`__reduce__`.
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
More information about the Python-checkins
mailing list