8000 pickle docs: Fix typos and improve wording (GH-24776) (GH-32396) · hello-adam/cpython@07b7ab2 · GitHub
[go: up one dir, main page]

Skip to content

Commit 07b7ab2

Browse files
miss-islingtongeryogam
authored andcommitted
pickle docs: Fix typos and improve wording (pythonGH-24776) (pythonGH-32396)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> (cherry picked from commit 1d0f08f) Co-authored-by: Géry Ogam <gery.ogam@gmail.com>
1 parent d5d4f91 commit 07b7ab2

File tree

1 file changed

+23
-24
lines changed

1 file changed

+23
-24
lines changed

Doc/library/pickle.rst

Lines changed: 23 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ to read the pickle produced.
147147
earlier versions of Python.
148148

149149
* Protocol version 2 was introduced in Python 2.3. It provides much more
150-
efficient pickling of :term:`new-style class`\es. Refer to :pep:`307` for
150+
efficient pickling of :term:`new-style classes <new-style class>`. Refer to :pep:`307` for
151151
information about improvements brought by protocol 2.
152152

153153
* Protocol version 3 was added in Python 3.0. It has explicit support for
@@ -261,7 +261,7 @@ process more convenient:
261261
protocol argument is needed. Bytes past the pickled representation
262262
of the object are ignored.
263263

264-
Arguments *file*, *fix_imports*, *encoding*, *errors*, *strict* and *buffers*
264+
Arguments *fix_imports*, *encoding*, *errors*, *strict* and *buffers*
265265
have the same meaning as in the :class:`Unpickler` constructor.
266266

267267
.. versionchanged:: 3.8
@@ -368,7 +368,7 @@ The :mod:`pickle` module exports three classes, :class:`Pickler`,
368368

369369
.. versionadded:: 3.3
370370

371-
.. method:: reducer_override(self, obj)
371+
.. method:: reducer_override(obj)
372372

373373
Special reducer that can be defined in :class:`Pickler` subclasses. This
374374
method has priority over any reducer in the :attr:`dispatch_table`. It
@@ -494,20 +494,18 @@ What can be pickled and unpickled?
494494

495495
The following types can be pickled:
496496

497-
* ``None``, ``True``, and ``False``
498-
499-
* integers, floating point numbers, complex numbers
497+
* ``None``, ``True``, and ``False``;
500498

501-
* strings, bytes, bytearrays
499+
* integers, floating-point numbers, complex numbers;
502500

503-
* tuples, lists, sets, and dictionaries containing only picklable objects
501+
* strings, bytes, bytearrays;
504502

505-
* functions defined at the top level of a module (using :keyword:`def`, not
506-
:keyword:`lambda`)
503+
* tuples, lists, sets, and dictionaries containing only picklable objects;
507504

508-
* built-in functions defined at the top level of a module
505+
* functions (built-in and user-defined) defined at the top level of a module
506+
(using :keyword:`def`, not :keyword:`lambda`);
509507

510-
* classes that are defined at the top level of a module
508+
* classes defined at the top level of a module;
511509

512510
* instances of such classes whose :attr:`~object.__dict__` or the result of
513511
calling :meth:`__getstate__` is picklable (see section :ref:`pickle-inst` for
@@ -520,14 +518,14 @@ structure may exceed the maximum recursion depth, a :exc:`RecursionError` will b
520518
raised in this case. You can carefully raise this limit with
521519
:func:`sys.setrecursionlimit`.
522520

523-
Note that functions (built-in and user-defined) are pickled by "fully qualified"
524-
name reference, not by value. [#]_ This means that only the function name is
521+
Note that functions (built-in and user-defined) are pickled by fully qualified
522+
name, not by value. [#]_ This means that only the function name is
525523
pickled, along with the name of the module the function is defined in. Neither
526524
the function's code, nor any of its function attributes are pickled. Thus the
527525
defining module must be importable in the unpickling environment, and the module
528526
must contain the named object, otherwise an exception will be raised. [#]_
529527

530-
Similarly, classes are pickled by named reference, so the same restrictions in
528+
Similarly, classes are pickled by fully qualified name, so the same restrictions in
531529
the unpickling environment apply. Note that none of the class's code or data is
532530
pickled, so in the following example the class attribute ``attr`` is not
533531
restored in the unpickling environment::
@@ -537,7 +535,7 @@ restored in the unpickling environment::
537535

538536
picklestring = pickle.dumps(Foo)
539537

540-
These restrictions are why picklable functions and classes must be defined in
538+
These restrictions are why picklable functions and classes must be defined at
541539
the top level of a module.
542540

543541
Similarly, when class instances are pickled, their class's code and data are not
@@ -569,7 +567,7 @@ implementation of this behaviour::
569567
def save(obj):
570568
return (obj.__class__, obj.__dict__)
571569

572-
def load(cls, attributes):
570+
def restore(cls, attributes):
573571
obj = cls.__new__(cls)
574572
obj.__dict__.update(attributes)
575573
return obj
@@ -788,14 +786,15 @@ the code ::
788786
f = io.BytesIO()
789787
p = MyPickler(f)
790788

791-
does the same, but all instances of ``MyPickler`` will by default
792-
share the same dispatch table. The equivalent code using the
793-
:mod:`copyreg` module is ::
789+
does the same but all instances of ``MyPickler`` will by default
790+
share the private dispatch table. On the other hand, the code ::
794791

795792
copyreg.pickle(SomeClass, reduce_SomeClass)
796793
f = io.BytesIO()
797794
p = pickle.Pickler(f)
798795

796+
modifies the global dispatch table shared by all users of the :mod:`copyreg` module.
797+
799798
.. _pickle-state:
800799

801800
Handling Stateful Objects
@@ -1098,7 +1097,7 @@ Here is an example of an unpickler allowing only few safe classes from the
10981097
"""Helper function analogous to pickle.loads()."""
10991098
return RestrictedUnpickler(io.BytesIO(s)).load()
11001099

1101-
A sample usage of our unpickler working has intended::
1100+
A sample usage of our unpickler working as intended::
11021101

11031102
>>> restricted_loads(pickle.dumps([1, 2, range(15)]))
11041103
[1, 2, range(0, 15)]
@@ -1142,7 +1141,7 @@ For the simplest code, use the :func:`dump` and :func:`load` functions. ::
11421141

11431142
# An arbitrary collection of objects supported by pickle.
11441143
data = {
1145-
'a': [1, 2.0, 3, 4+6j],
1144+
'a': [1, 2.0, 3+4j],
11461145
'b': ("character string", b"byte string"),
11471146
'c': {None, True, False}
11481147
}
@@ -1198,6 +1197,6 @@ The following example reads the resulting pickled data. ::
11981197
operations.
11991198
12001199
.. [#] The limitation on alphanumeric characters is due to the fact
1201-
the persistent IDs, in protocol 0, are delimited by the newline
1200+
that persistent IDs in protocol 0 are delimited by the newline
12021201
character. Therefore if any kind of newline characters occurs in
1203-
persistent IDs, the resulting pickle will become unreadable.
1202+
persistent IDs, the resulting pickled data will become unreadable.

0 commit comments

Comments
 (0)
0