[Python-checkins] pickle docs: Fix typos and improve wording (GH-24776)

[JelleZijlstra]

https://github.com/python/cpython/commit/1d0f08fa46b54f5a9b43a916b66d50b97d56cf36
commit: 1d0f08fa46b54f5a9b43a916b66d50b97d56cf36
branch: main
author: Géry Ogam <gery.ogam at gmail.com>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2022-04-06T18:38:35-07:00
summary:

pickle docs: Fix typos and improve wording (GH-24776)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra at gmail.com>

files:
M Doc/library/pickle.rst

diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index a8ad5d437aaab..fa14b64027e8f 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.