diff options
Diffstat (limited to 'Doc/library/pickle.rst')
| -rw-r--r-- | Doc/library/pickle.rst | 176 |
1 files changed, 91 insertions, 85 deletions
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index 3358053..8a671a7 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -23,6 +23,12 @@ into an object hierarchy. Pickling (and unpickling) is alternatively known as "serialization", "marshalling," [#]_ or "flattening", however, to avoid confusion, the terms used here are "pickling" and "unpickling".. +.. warning:: + + The :mod:`pickle` module is not intended to be secure against erroneous or + maliciously constructed data. Never unpickle data received from an untrusted + or unauthenticated source. + Relationship to other Python modules ------------------------------------ @@ -63,12 +69,6 @@ The :mod:`pickle` module differs from :mod:`marshal` several significant ways: The :mod:`pickle` serialization format is guaranteed to be backwards compatible across Python releases. -.. warning:: - - The :mod:`pickle` module is not intended to be secure against erroneous or - maliciously constructed data. Never unpickle data received from an untrusted - or unauthenticated source. - Note that serialization is a more primitive notion than persistence; although :mod:`pickle` reads and writes file objects, it does not handle the issue of naming persistent objects, nor the (even more complicated) issue of concurrent @@ -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. - -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: |