gh-101100: Fix dangling references in pickle.rst (#114972)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
This commit is contained in:
Skip Montanaro 2024-02-04 08:24:24 -06:00 committed by GitHub
parent 848c86786b
commit ec69e1d0dd
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 26 additions and 26 deletions

View File

@ -356,7 +356,7 @@ The :mod:`pickle` module exports three classes, :class:`Pickler`,
:func:`copyreg.pickle`. It is a mapping whose keys are classes
and whose values are reduction functions. A reduction function
takes a single argument of the associated class and should
conform to the same interface as a :meth:`__reduce__`
conform to the same interface as a :meth:`~object.__reduce__`
method.
By default, a pickler object will not have a
@ -376,7 +376,7 @@ The :mod:`pickle` module exports three classes, :class:`Pickler`,
Special reducer that can be defined in :class:`Pickler` subclasses. This
method has priority over any reducer in the :attr:`dispatch_table`. It
should conform to the same interface as a :meth:`__reduce__` method, and
should conform to the same interface as a :meth:`~object.__reduce__` method, and
can optionally return ``NotImplemented`` to fallback on
:attr:`dispatch_table`-registered reducers to pickle ``obj``.
@ -516,7 +516,7 @@ The following types can be pickled:
* classes accessible from the top level of a module;
* instances of such classes whose the result of calling :meth:`__getstate__`
* instances of such classes whose the result of calling :meth:`~object.__getstate__`
is picklable (see section :ref:`pickle-inst` for details).
Attempts to pickle unpicklable objects will raise the :exc:`PicklingError`
@ -552,7 +552,7 @@ purpose, so you can fix bugs in a class or add methods to the class and still
load objects that were created with an earlier version of the class. If you
plan to have long-lived objects that will see many versions of a class, it may
be worthwhile to put a version number in the objects so that suitable
conversions can be made by the class's :meth:`__setstate__` method.
conversions can be made by the class's :meth:`~object.__setstate__` method.
.. _pickle-inst:
@ -567,7 +567,7 @@ customize, and control how class instances are pickled and unpickled.
In most cases, no additional code is needed to make instances picklable. By
default, pickle will retrieve the class and the attributes of an instance via
introspection. When a class instance is unpickled, its :meth:`__init__` method
introspection. When a class instance is unpickled, its :meth:`~object.__init__` method
is usually *not* invoked. The default behaviour first creates an uninitialized
instance and then restores the saved attributes. The following code shows an
implementation of this behaviour::
@ -658,30 +658,30 @@ methods:
Refer to the section :ref:`pickle-state` for more information about how to use
the methods :meth:`__getstate__` and :meth:`__setstate__`.
the methods :meth:`~object.__getstate__` and :meth:`~object.__setstate__`.
.. note::
At unpickling time, some methods like :meth:`__getattr__`,
:meth:`__getattribute__`, or :meth:`__setattr__` may be called upon the
At unpickling time, some methods like :meth:`~object.__getattr__`,
:meth:`~object.__getattribute__`, or :meth:`~object.__setattr__` may be called upon the
instance. In case those methods rely on some internal invariant being
true, the type should implement :meth:`__new__` to establish such an
invariant, as :meth:`__init__` is not called when unpickling an
true, the type should implement :meth:`~object.__new__` to establish such an
invariant, as :meth:`~object.__init__` is not called when unpickling an
instance.
.. index:: pair: copy; protocol
As we shall see, pickle does not use directly the methods described above. In
fact, these methods are part of the copy protocol which implements the
:meth:`__reduce__` special method. The copy protocol provides a unified
:meth:`~object.__reduce__` special method. The copy protocol provides a unified
interface for retrieving the data necessary for pickling and copying
objects. [#]_
Although powerful, implementing :meth:`__reduce__` directly in your classes is
Although powerful, implementing :meth:`~object.__reduce__` directly in your classes is
error prone. For this reason, class designers should use the high-level
interface (i.e., :meth:`__getnewargs_ex__`, :meth:`__getstate__` and
:meth:`__setstate__`) whenever possible. We will show, however, cases where
using :meth:`__reduce__` is the only option or leads to more efficient pickling
interface (i.e., :meth:`~object.__getnewargs_ex__`, :meth:`~object.__getstate__` and
:meth:`~object.__setstate__`) whenever possible. We will show, however, cases where
using :meth:`!__reduce__` is the only option or leads to more efficient pickling
or both.
.. method:: object.__reduce__()
@ -716,8 +716,9 @@ or both.
These items will be appended to the object either using
``obj.append(item)`` or, in batch, using ``obj.extend(list_of_items)``.
This is primarily used for list subclasses, but may be used by other
classes as long as they have :meth:`append` and :meth:`extend` methods with
the appropriate signature. (Whether :meth:`append` or :meth:`extend` is
classes as long as they have
:ref:`append and extend methods <typesseq-common>` with
the appropriate signature. (Whether :meth:`!append` or :meth:`!extend` is
used depends on which pickle protocol version is used as well as the number
of items to append, so both must be supported.)
@ -793,8 +794,8 @@ any other code which depends on pickling, then one can create a
pickler with a private dispatch table.
The global dispatch table managed by the :mod:`copyreg` module is
available as :data:`copyreg.dispatch_table`. Therefore, one may
choose to use a modified copy of :data:`copyreg.dispatch_table` as a
available as :data:`!copyreg.dispatch_table`. Therefore, one may
choose to use a modified copy of :data:`!copyreg.dispatch_table` as a
private dispatch table.
For example ::
@ -833,12 +834,12 @@ Handling Stateful Objects
single: __setstate__() (copy protocol)
Here's an 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 below opens a text file, and returns the line number and
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
reading resumes from the last location. The :meth:`__setstate__` and
:meth:`__getstate__` methods are used to implement this behavior. ::
reading resumes from the last location. The :meth:`!__setstate__` and
:meth:`!__getstate__` methods are used to implement this behavior. ::
class TextReader:
"""Print and number lines in a text file."""
@ -903,7 +904,7 @@ functions and classes.
For those cases, it is possible to subclass from the :class:`Pickler` class and
implement a :meth:`~Pickler.reducer_override` method. This method can return an
arbitrary reduction tuple (see :meth:`__reduce__`). It can alternatively return
arbitrary reduction tuple (see :meth:`~object.__reduce__`). It can alternatively return
``NotImplemented`` to fallback to the traditional behavior.
If both the :attr:`~Pickler.dispatch_table` and
@ -971,7 +972,7 @@ provided by pickle protocol 5 and higher.
Provider API
^^^^^^^^^^^^
The large data objects to be pickled must implement a :meth:`__reduce_ex__`
The large data objects to be pickled must implement a :meth:`~object.__reduce_ex__`
method specialized for protocol 5 and higher, which returns a
:class:`PickleBuffer` instance (instead of e.g. a :class:`bytes` object)
for any large data.

View File

@ -46,7 +46,6 @@ Doc/library/mmap.rst
Doc/library/multiprocessing.rst
Doc/library/optparse.rst
Doc/library/os.rst
Doc/library/pickle.rst
Doc/library/pickletools.rst
Doc/library/platform.rst
Doc/library/plistlib.rst