diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index 2d01d8b7ab2..f741976c930 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -189,8 +189,9 @@ process more convenient: .. function:: dump(obj, file, protocol=None, \*, fix_imports=True) - Write a pickled representation of *obj* to the open :term:`file object` *file*. - This is equivalent to ``Pickler(file, protocol).dump(obj)``. + Write the pickled representation of the object *obj* to the open + :term:`file object` *file*. This is equivalent to + ``Pickler(file, protocol).dump(obj)``. The optional *protocol* argument, an integer, tells the pickler to use the given protocol; supported protocols are 0 to :data:`HIGHEST_PROTOCOL`. @@ -208,7 +209,7 @@ process more convenient: .. function:: dumps(obj, protocol=None, \*, fix_imports=True) - Return the pickled representation of the object as a :class:`bytes` object, + Return the pickled representation of the object *obj* as a :class:`bytes` object, instead of writing it to a file. Arguments *protocol* and *fix_imports* have the same meaning as in @@ -216,13 +217,13 @@ process more convenient: .. function:: load(file, \*, fix_imports=True, encoding="ASCII", errors="strict") - Read a pickled object representation from the open :term:`file object` + Read the pickled representation of an object from the open :term:`file object` *file* and return the reconstituted object hierarchy specified therein. This is equivalent to ``Unpickler(file).load()``. The protocol version of the pickle is detected automatically, so no - protocol argument is needed. Bytes past the pickled object's - representation are ignored. + protocol argument is needed. Bytes past the pickled representation + of the object are ignored. The argument *file* must have two methods, a read() method that takes an integer argument, and a readline() method that requires no arguments. Both @@ -243,12 +244,12 @@ process more convenient: .. function:: loads(bytes_object, \*, fix_imports=True, encoding="ASCII", errors="strict") - Read a pickled object hierarchy from a :class:`bytes` object and return the - reconstituted object hierarchy specified therein. + Return the reconstituted object hierarchy of the pickled representation + *bytes_object* of an object. The protocol version of the pickle is detected automatically, so no - protocol argument is needed. Bytes past the pickled object's - representation are ignored. + protocol argument is needed. Bytes past the pickled representation + of the object are ignored. Optional keyword arguments are *fix_imports*, *encoding* and *errors*, which are used to control compatibility support for pickle stream generated @@ -310,7 +311,7 @@ The :mod:`pickle` module exports two classes, :class:`Pickler` and .. method:: dump(obj) - Write a pickled representation of *obj* to the open file object given in + Write the pickled representation of *obj* to the open file object given in the constructor. .. method:: persistent_id(obj) @@ -382,9 +383,10 @@ The :mod:`pickle` module exports two classes, :class:`Pickler` and .. method:: load() - Read a pickled object representation from the open file object given in - the constructor, and return the reconstituted object hierarchy specified - therein. Bytes past the pickled object's representation are ignored. + Read the pickled representation of an object from the open file object + given in the constructor, and return the reconstituted object hierarchy + specified therein. Bytes past the pickled representation of the object + are ignored. .. method:: persistent_load(pid) @@ -649,13 +651,13 @@ alphanumeric characters (for protocol 0) [#]_ or just an arbitrary object (for any newer protocol). 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 +module; it will delegate this resolution to the user-defined methods on the 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 +To pickle objects that have an external persistent ID, the pickler must have a custom :meth:`~Pickler.persistent_id` method that takes an object as an -argument and returns either ``None`` or the persistent id for that object. +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.