diff -r 7d94034e1ddc Doc/library/pickle.rst --- a/Doc/library/pickle.rst Sun Oct 06 10:51:07 2013 +0200 +++ b/Doc/library/pickle.rst Mon Oct 07 23:03:34 2013 +0300 @@ -294,7 +294,7 @@ :func:`copyreg.pickle`. It is a mapping whose keys are classes and whose values are reduction functions. A reduction function takes a single argument of the associated class and should - conform to the same interface as a :meth:`~object.__reduce__` + conform to the same interface as a :meth:`~.object.__reduce__` method. By default, a pickler object will not have a @@ -390,9 +390,9 @@ * classes that are defined at the top level of a module -* instances of such classes whose :attr:`__dict__` or the result of calling - :meth:`__getstate__` is picklable (see section :ref:`pickle-inst` for - details). +* instances of such classes whose :attr:`~object.__dict__` or the result of + calling :meth:`~.object.__getstate__` is picklable (see section + :ref:`pickle-inst` for details). Attempts to pickle unpicklable objects will raise the :exc:`PicklingError` exception; when this happens, an unspecified number of bytes may have already @@ -427,7 +427,7 @@ load objects that were created with an earlier version of the class. If you plan to have long-lived objects that will see many versions of a class, it may be worthwhile to put a version number in the objects so that suitable -conversions can be made by the class's :meth:`__setstate__` method. +conversions can be made by the class's :meth:`~.object.__setstate__` method. .. _pickle-inst: @@ -435,15 +435,17 @@ Pickling Class Instances ------------------------ +.. currentmodule:: . + In this section, we describe the general mechanisms available to you to define, customize, and control how class instances are pickled and unpickled. In most cases, no additional code is needed to make instances picklable. By default, pickle will retrieve the class and the attributes of an instance via -introspection. When a class instance is unpickled, its :meth:`__init__` method -is usually *not* invoked. The default behaviour first creates an uninitialized -instance and then restores the saved attributes. The following code shows an -implementation of this behaviour:: +introspection. When a class instance is unpickled, its :meth:`~object.__init__` +method is usually *not* invoked. The default behaviour first creates an +uninitialized instance and then restores the saved attributes. The following +code shows an implementation of this behaviour:: def save(obj): return (obj.__class__, obj.__dict__) @@ -458,66 +460,68 @@ .. 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. + In protocol 2 and newer, classes that implements the + :meth:`~object.__getnewargs__` method can dictate the values passed to the + :meth:`~object.__new__` method upon unpickling. This is often needed for + classes whose :meth:`~object.__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. + defines the method :meth:`~object.__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:`~object.__getstate__` + method is absent, the instance's :attr:`~object.__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. + Upon unpickling, if the class defines :meth:`~object.__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:`~object.__getstate__` returns a false value, the + :meth:`~object.__setstate__` method will not be called upon unpickling. Refer to the section :ref:`pickle-state` for more information about how to use -the methods :meth:`__getstate__` and :meth:`__setstate__`. +the methods :meth:`~object.__getstate__` and :meth:`~object.__setstate__`. .. note:: - 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 :meth:`__getnewargs__` to establish such an - invariant; otherwise, neither :meth:`__new__` nor :meth:`__init__` will be - called. + At unpickling time, some methods like :meth:`~object.__getattr__`, + :meth:`~object.__getattribute__`, or :meth:`~object.__setattr__` may be + called upon the instance. In case those methods rely on some internal + invariant being true, the type should implement + :meth:`~object.__getnewargs__` to establish such an invariant; otherwise, + neither :meth:`~object.__new__` nor :meth:`~object.__init__` will be called. .. 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 -:meth:`__reduce__` special method. The copy protocol provides a unified +:meth:`~object.__reduce__` special method. The copy protocol provides a unified interface for retrieving the data necessary for pickling and copying 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. +Although powerful, implementing :meth:`~object.__reduce__` directly in your +classes is error prone. For this reason, class designers should use the +high-level interface (i.e., :meth:`~object.__getnewargs__`, +:meth:`~object.__getstate__` and :meth:`~object.__setstate__`) whenever +possible. We will show, however, cases where using :meth:`~object.__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"). + The interface is currently defined as follows. The + :meth:`~object.__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 @@ -537,9 +541,9 @@ 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. + :meth:`~object.__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:`~object.__dict__` attribute. * Optionally, an iterator (and not a sequence) yielding successive items. These items will be appended to the object either using @@ -553,17 +557,20 @@ * 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__`. + by other classes as long as they implement :meth:`~object.__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. + Alternatively, a :meth:`~object.__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:`~object.__reduce__` method. In addition, :meth:`~object.__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. + +.. currentmodule:: pickle .. _pickle-persistent: @@ -582,19 +589,19 @@ The resolution of such persistent IDs is not defined by the :mod:`pickle` module; it will delegate this resolution to the user defined methods on the -pickler and unpickler, :meth:`persistent_id` and :meth:`persistent_load` -respectively. +pickler and unpickler, :meth:`~Pickler.persistent_id` and +:meth:`~Unpickler.persistent_load` respectively. To pickle objects that have an external persistent id, the pickler must have a -custom :meth:`persistent_id` method that takes an object as an argument and -returns either ``None`` or the persistent id for that object. When ``None`` is -returned, the pickler simply pickles the object as normal. When a persistent ID -string is returned, the pickler will pickle that object, along with a marker so -that the unpickler will recognize it as a persistent ID. +custom :meth:`~Pickler.persistent_id` method that takes an object as an +argument and returns either ``None`` or the persistent id for that object. +When ``None`` is returned, the pickler simply pickles the object as normal. +When a persistent ID string is returned, the pickler will pickle that object, +along with a marker so that the unpickler will recognize it as a persistent ID. To unpickle external objects, the unpickler must have a custom -:meth:`persistent_load` method that takes a persistent ID object and returns the -referenced object. +:meth:`~Unpickler.persistent_load` method that takes a persistent ID object and +returns the referenced object. Here is a comprehensive example presenting how persistent ID can be used to pickle external objects by reference. @@ -651,11 +658,11 @@ Here's an example that shows how to modify pickling behavior for a class. The :class:`TextReader` class opens a text file, and returns the line number and -line contents each time its :meth:`readline` method is called. If a +line contents each time its :meth:`!readline` method is called. If a :class:`TextReader` instance is pickled, all attributes *except* the file object member are saved. When the instance is unpickled, the file is reopened, and -reading resumes from the last location. The :meth:`__setstate__` and -:meth:`__getstate__` methods are used to implement this behavior. :: +reading resumes from the last location. The :meth:`~.object.__setstate__` and +:meth:`~.object.__getstate__` methods are used to implement this behavior. :: class TextReader: """Print and number lines in a text file.""" @@ -730,9 +737,10 @@ inoffensive, it is not difficult to imagine one that could damage your system. For this reason, you may want to control what gets unpickled by customizing -:meth:`Unpickler.find_class`. Unlike its name suggests, :meth:`find_class` is -called whenever a global (i.e., a class or a function) is requested. Thus it is -possible to either completely forbid globals or restrict them to a safe subset. +:meth:`Unpickler.find_class`. Unlike its name suggests, +:meth:`Unpickler.find_class` is called whenever a global (i.e., a class or +a function) is requested. Thus it is possible to either completely forbid +globals or restrict them to a safe subset. Here is an example of an unpickler allowing only few safe classes from the :mod:`builtins` module to be loaded::