[Python-checkins] r85638 - python/branches/py3k/Doc/library/pickle.rst
georg.brandl
python-checkins at python.org
Sun Oct 17 13:13:37 CEST 2010
Author: georg.brandl
Date: Sun Oct 17 13:13:37 2010
New Revision: 85638
Log:
Port changes to pickle docs apparently lost in py3k.
Modified:
python/branches/py3k/Doc/library/pickle.rst
Modified: python/branches/py3k/Doc/library/pickle.rst
==============================================================================
--- python/branches/py3k/Doc/library/pickle.rst (original)
+++ python/branches/py3k/Doc/library/pickle.rst Sun Oct 17 13:13:37 2010
@@ -427,33 +427,38 @@
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.
-
-.. index:: single: __getstate__() (copy protocol)
-
-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.
-
-.. 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.
+methods:
-.. note::
+.. method:: object.__getnewargs__()
+
+ 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.
+
+
+.. 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 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 @@
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 @@
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.
-
-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").
-
-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.
-
-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:
-
-.. XXX Mention __newobj__ special-case?
-
-* A callable object that will be called to create the initial version of the
- object.
-
-* A tuple of arguments for the callable object. An empty tuple must be given if
- the callable does not accept any argument.
-
-* 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 (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, 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__`.
-
-.. index:: single: __reduce_ex__() (copy 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.
+: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.
+
+.. method:: object.__reduce__()
+
+ 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").
+
+ 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.
+
+ 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:
+
+ .. XXX Mention __newobj__ special-case?
+
+ * A callable object that will be called to create the initial version of the
+ object.
+
+ * A tuple of arguments for the callable object. An empty tuple must be given
+ if the callable does not accept any argument.
+
+ * 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 (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, 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__`.
+
+
+.. 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:
More information about the Python-checkins
mailing list