Commit 0b9a9fd3 authored by Serhiy Storchaka's avatar Serhiy Storchaka

Issue #19189: Improved cross-references in the pickle module documentation.

parent 28523641
...@@ -352,9 +352,9 @@ The following types can be pickled: ...@@ -352,9 +352,9 @@ The following types can be pickled:
* classes that are defined at the top level of a module * classes that are defined at the top level of a module
* instances of such classes whose :attr:`__dict__` or the result of calling * instances of such classes whose :attr:`~object.__dict__` or the result of
:meth:`__getstate__` is picklable (see section :ref:`pickle-protocol` for calling :meth:`__getstate__` is picklable (see section :ref:`pickle-protocol`
details). for details).
Attempts to pickle unpicklable objects will raise the :exc:`PicklingError` Attempts to pickle unpicklable objects will raise the :exc:`PicklingError`
exception; when this happens, an unspecified number of bytes may have already exception; when this happens, an unspecified number of bytes may have already
...@@ -443,7 +443,7 @@ Pickling and unpickling normal class instances ...@@ -443,7 +443,7 @@ Pickling and unpickling normal class instances
defines the method :meth:`__getstate__`, it is called and the return state is 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 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 dictionary. If there is no :meth:`__getstate__` method, the
instance's :attr:`__dict__` is pickled. instance's :attr:`~object.__dict__` is pickled.
.. method:: object.__setstate__(state) .. method:: object.__setstate__(state)
...@@ -511,7 +511,8 @@ Pickling and unpickling extension types ...@@ -511,7 +511,8 @@ Pickling and unpickling extension types
* Optionally, the object's state, which will be passed to the object's * Optionally, the object's state, which will be passed to the object's
:meth:`__setstate__` method as described in section :ref:`pickle-inst`. If :meth:`__setstate__` method as described in section :ref:`pickle-inst`. If
the object has no :meth:`__setstate__` method, then, as above, the value 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__`. must be a dictionary and it will be added to the object's
:attr:`~object.__dict__`.
* Optionally, an iterator (and not a sequence) yielding successive list * Optionally, an iterator (and not a sequence) yielding successive list
items. These list items will be pickled, and appended to the object using items. These list items will be pickled, and appended to the object using
...@@ -569,19 +570,20 @@ the :mod:`pickle` module; it will delegate this resolution to user defined ...@@ -569,19 +570,20 @@ the :mod:`pickle` module; it will delegate this resolution to user defined
functions on the pickler and unpickler. [#]_ functions on the pickler and unpickler. [#]_
To define external persistent id resolution, you need to set the To define external persistent id resolution, you need to set the
:attr:`persistent_id` attribute of the pickler object and the :attr:`~Pickler.persistent_id` attribute of the pickler object and the
:attr:`persistent_load` attribute of the unpickler object. :attr:`~Unpickler.persistent_load` attribute of the unpickler object.
To pickle objects that have an external persistent id, the pickler must have a To pickle objects that have an external persistent id, the pickler must have a
custom :func:`persistent_id` method that takes an object as an argument and custom :func:`~Pickler.persistent_id` method that takes an object as an
returns either ``None`` or the persistent id for that object. When ``None`` is argument and returns either ``None`` or the persistent id for that object.
returned, the pickler simply pickles the object as normal. When a persistent id When ``None`` is returned, the pickler simply pickles the object as normal.
string is returned, the pickler will pickle that string, along with a marker so When a persistent id string is returned, the pickler will pickle that string,
that the unpickler will recognize the string as a persistent id. along with a marker so that the unpickler will recognize the string as a
persistent id.
To unpickle external objects, the unpickler must have a custom To unpickle external objects, the unpickler must have a custom
:func:`persistent_load` function that takes a persistent id string and returns :func:`~Unpickler.persistent_load` function that takes a persistent id string
the referenced object. and returns the referenced object.
Here's a silly example that *might* shed more light:: Here's a silly example that *might* shed more light::
...@@ -631,13 +633,14 @@ Here's a silly example that *might* shed more light:: ...@@ -631,13 +633,14 @@ Here's a silly example that *might* shed more light::
j = up.load() j = up.load()
print j print j
In the :mod:`cPickle` module, the unpickler's :attr:`persistent_load` attribute In the :mod:`cPickle` module, the unpickler's :attr:`~Unpickler.persistent_load`
can also be set to a Python list, in which case, when the unpickler reaches a attribute can also be set to a Python list, in which case, when the unpickler
persistent id, the persistent id string will simply be appended to this list. reaches a persistent id, the persistent id string will simply be appended to
This functionality exists so that a pickle data stream can be "sniffed" for this list. This functionality exists so that a pickle data stream can be
object references without actually instantiating all the objects in a pickle. "sniffed" for object references without actually instantiating all the objects
[#]_ Setting :attr:`persistent_load` to a list is usually used in conjunction in a pickle.
with the :meth:`noload` method on the Unpickler. [#]_ Setting :attr:`~Unpickler.persistent_load` to a list is usually used in
conjunction with the :meth:`~Unpickler.noload` method on the Unpickler.
.. BAW: Both pickle and cPickle support something called inst_persistent_id() .. BAW: Both pickle and cPickle support something called inst_persistent_id()
which appears to give unknown types a second shot at producing a persistent which appears to give unknown types a second shot at producing a persistent
...@@ -675,13 +678,13 @@ want to disallow all unpickling of instances. If this sounds like a hack, ...@@ -675,13 +678,13 @@ want to disallow all unpickling of instances. If this sounds like a hack,
you're right. Refer to the source code to make this work. you're right. Refer to the source code to make this work.
Things are a little cleaner with :mod:`cPickle`, but not by much. To control Things are a little cleaner with :mod:`cPickle`, but not by much. To control
what gets unpickled, you can set the unpickler's :attr:`find_global` attribute what gets unpickled, you can set the unpickler's :attr:`~Unpickler.find_global`
to a function or ``None``. If it is ``None`` then any attempts to unpickle attribute to a function or ``None``. If it is ``None`` then any attempts to
instances will raise an :exc:`UnpicklingError`. If it is a function, then it unpickle instances will raise an :exc:`UnpicklingError`. If it is a function,
should accept a module name and a class name, and return the corresponding class then it should accept a module name and a class name, and return the
object. It is responsible for looking up the class and performing any necessary corresponding class object. It is responsible for looking up the class and
imports, and it may raise an error to prevent instances of the class from being performing any necessary imports, and it may raise an error to prevent
unpickled. instances of the class from being unpickled.
The moral of the story is that you should be really careful about the source of The moral of the story is that you should be really careful about the source of
the strings your application unpickles. the strings your application unpickles.
...@@ -732,7 +735,7 @@ can't be sure if the ASCII or binary format was used. :: ...@@ -732,7 +735,7 @@ can't be sure if the ASCII or binary format was used. ::
Here's a larger example that shows how to modify pickling behavior for a class. Here's a larger 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 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 :class:`TextReader` instance is pickled, all attributes *except* the file object
member are saved. When the instance is unpickled, the file is reopened, and member are saved. When the instance is unpickled, the file is reopened, and
reading resumes from the last location. The :meth:`__setstate__` and reading resumes from the last location. The :meth:`__setstate__` and
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment