[3.14] gh-148669: Clarify `__reduce__()` module lookup behavior (GH-148670) (#149704)

gh-148669: Clarify `__reduce__()` module lookup behavior (GH-148670)
(cherry picked from commit 54a5fd4126df74f7b84d1f8a6a36ef79803f66f9)

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index 02b79a9f3a7a47adab899e63bed34c5bb37014f0..efae4910ca4358585e2093dc17844bc59fd15453 100644 (file)
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -59,7 +59,7 @@ The :mod:`!pickle` module differs from :mod:`marshal` in several significant way
 * :mod:`marshal` cannot be used to serialize user-defined classes and their
   instances.  :mod:`!pickle` can save and restore class instances transparently,
   however the class definition must be importable and live in the same module as
-  when the object was stored.
+  when the object was pickled.
 
 * The :mod:`marshal` serialization format is not guaranteed to be portable
   across Python versions.  Because its primary job in life is to support
@@ -696,7 +696,10 @@ or both.
    If a string is returned, the string should be interpreted as the name of a
    global variable.  It should be the object's local name relative to its
    module; the pickle module searches the module namespace to determine the
-   object's module.  This behaviour is typically useful for singletons.
+   object's module: for a given ``obj`` to be pickled, the ``__module__``
+   attribute is looked up on ``obj`` directly, which falls back to a lookup
+   on the type of ``obj`` if no ``__module__`` instance attribute is set.
+   This behaviour is typically useful for singletons.
 
    When a tuple is returned, it must be between two and six items long.
    Optional items can either be omitted, or ``None`` can be provided as their