diff options
| -rw-r--r-- | Doc/library/pickle.rst | 47 |
1 files changed, 23 insertions, 24 deletions
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index a8ad5d4..fa14b64 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -147,7 +147,7 @@ to read the pickle produced. earlier versions of Python. * Protocol version 2 was introduced in Python 2.3. It provides much more - efficient pickling of :term:`new-style class`\es. Refer to :pep:`307` for + efficient pickling of :term:`new-style classes <new-style class>`. Refer to :pep:`307` for information about improvements brought by protocol 2. * Protocol version 3 was added in Python 3.0. It has explicit support for @@ -261,7 +261,7 @@ process more convenient: protocol argument is needed. Bytes past the pickled representation of the object are ignored. - Arguments *file*, *fix_imports*, *encoding*, *errors*, *strict* and *buffers* + Arguments *fix_imports*, *encoding*, *errors*, *strict* and *buffers* have the same meaning as in the :class:`Unpickler` constructor. .. versionchanged:: 3.8 @@ -368,7 +368,7 @@ The :mod:`pickle` module exports three classes, :class:`Pickler`, .. versionadded:: 3.3 - .. method:: reducer_override(self, obj) + .. method:: reducer_override(obj) Special reducer that can be defined in :class:`Pickler` subclasses. This method has priority over any reducer in the :attr:`dispatch_table`. It @@ -494,20 +494,18 @@ What can be pickled and unpickled? The following types can be pickled: -* ``None``, ``True``, and ``False`` - -* integers, floating point numbers, complex numbers +* ``None``, ``True``, and ``False``; -* strings, bytes, bytearrays +* integers, floating-point numbers, complex numbers; -* tuples, lists, sets, and dictionaries containing only picklable objects +* strings, bytes, bytearrays; -* functions defined at the top level of a module (using :keyword:`def`, not - :keyword:`lambda`) +* tuples, lists, sets, and dictionaries containing only picklable objects; -* built-in functions defined at the top level of a module +* functions (built-in and user-defined) defined at the top level of a module + (using :keyword:`def`, not :keyword:`lambda`); -* classes that are defined at the top level of a module +* classes defined at the top level of a module; * instances of such classes whose the result of calling :meth:`__getstate__` is picklable (see section :ref:`pickle-inst` for details). @@ -519,14 +517,14 @@ structure may exceed the maximum recursion depth, a :exc:`RecursionError` will b raised in this case. You can carefully raise this limit with :func:`sys.setrecursionlimit`. -Note that functions (built-in and user-defined) are pickled by "fully qualified" -name reference, not by value. [#]_ This means that only the function name is +Note that functions (built-in and user-defined) are pickled by fully qualified +name, not by value. [#]_ This means that only the function name is pickled, along with the name of the module the function is defined in. Neither the function's code, nor any of its function attributes are pickled. Thus the defining module must be importable in the unpickling environment, and the module must contain the named object, otherwise an exception will be raised. [#]_ -Similarly, classes are pickled by named reference, so the same restrictions in +Similarly, classes are pickled by fully qualified name, so the same restrictions in the unpickling environment apply. Note that none of the class's code or data is pickled, so in the following example the class attribute ``attr`` is not restored in the unpickling environment:: @@ -536,7 +534,7 @@ restored in the unpickling environment:: picklestring = pickle.dumps(Foo) -These restrictions are why picklable functions and classes must be defined in +These restrictions are why picklable functions and classes must be defined at the top level of a module. Similarly, when class instances are pickled, their class's code and data are not @@ -568,7 +566,7 @@ implementation of this behaviour:: def save(obj): return (obj.__class__, obj.__dict__) - def load(cls, attributes): + def restore(cls, attributes): obj = cls.__new__(cls) obj.__dict__.update(attributes) return obj @@ -807,14 +805,15 @@ the code :: f = io.BytesIO() p = MyPickler(f) -does the same, but all instances of ``MyPickler`` will by default -share the same dispatch table. The equivalent code using the -:mod:`copyreg` module is :: +does the same but all instances of ``MyPickler`` will by default +share the private dispatch table. On the other hand, the code :: copyreg.pickle(SomeClass, reduce_SomeClass) f = io.BytesIO() p = pickle.Pickler(f) +modifies the global dispatch table shared by all users of the :mod:`copyreg` module. + .. _pickle-state: Handling Stateful Objects @@ -1117,7 +1116,7 @@ Here is an example of an unpickler allowing only few safe classes from the """Helper function analogous to pickle.loads().""" return RestrictedUnpickler(io.BytesIO(s)).load() -A sample usage of our unpickler working has intended:: +A sample usage of our unpickler working as intended:: >>> restricted_loads(pickle.dumps([1, 2, range(15)])) [1, 2, range(0, 15)] @@ -1161,7 +1160,7 @@ For the simplest code, use the :func:`dump` and :func:`load` functions. :: # An arbitrary collection of objects supported by pickle. data = { - 'a': [1, 2.0, 3, 4+6j], + 'a': [1, 2.0, 3+4j], 'b': ("character string", b"byte string"), 'c': {None, True, False} } @@ -1217,6 +1216,6 @@ The following example reads the resulting pickled data. :: operations. .. [#] The limitation on alphanumeric characters is due to the fact - the persistent IDs, in protocol 0, are delimited by the newline + that persistent IDs in protocol 0 are delimited by the newline character. Therefore if any kind of newline characters occurs in - persistent IDs, the resulting pickle will become unreadable. + persistent IDs, the resulting pickled data will become unreadable. |