bpo-47220: Document the optional callback parameter of weakref.WeakMethod

Doc/library/weakref.rst

@@ -95,13 +95,13 @@ See :ref:`__slots__ documentation <slots>` for details.
 
 .. class:: ref(object[, callback])
 
-   Return a weak reference to *object*.  The original object can be retrieved by
-   calling the reference object if the referent is still alive; if the referent is
-   no longer alive, calling the reference object will cause :const:`None` to be
-   returned.  If *callback* is provided and not :const:`None`, and the returned
-   weakref object is still alive, the callback will be called when the object is
-   about to be finalized; the weak reference object will be passed as the only
-   parameter to the callback; the referent will no longer be available.
+   Return a weak reference to *object*.  The referent can be retrieved by
+   calling the weak reference if the referent is still alive; if the referent is
+   no longer alive, calling the weak reference will cause :const:`None` to be
+   returned.  If *callback* is provided and not :const:`None`, and the weak
+   reference is still alive, the callback will be called when the referent is
+   about to be finalized; the weak reference will be passed as the only
+   argument to the callback; the referent will no longer be available.
 
    It is allowable for many weak references to be constructed for the same object.
    Callbacks registered for each weak reference will be called from the most
@@ -117,9 +117,9 @@ See :ref:`__slots__ documentation <slots>` for details.
    the call will raise :exc:`TypeError`.
 
    Weak references support tests for equality, but not ordering.  If the referents
-   are still alive, two references have the same equality relationship as their
+   are still alive, two weak references have the same equality relationship as their
    referents (regardless of the *callback*).  If either referent has been deleted,
-   the references are equal only if the reference objects are the same object.
+   two weak references are equal only if the weak references are the same object.
 
    This is a subclassable type rather than a factory function.
 
@@ -137,15 +137,15 @@ See :ref:`__slots__ documentation <slots>` for details.
 
    Return a proxy to *object* which uses a weak reference.  This supports use of
    the proxy in most contexts instead of requiring the explicit dereferencing used
-   with weak reference objects.  The returned object will have a type of either
+   with weak references.  The returned object will have a type of either
    ``ProxyType`` or ``CallableProxyType``, depending on whether *object* is
-   callable.  Proxy objects are not :term:`hashable` regardless of the referent; this
+   callable.  Proxies are not :term:`hashable` regardless of the referent; this
    avoids a number of problems related to their fundamentally mutable nature, and
-   prevent their use as dictionary keys.  *callback* is the same as the parameter
+   prevents their use as dictionary keys.  *callback* is the same as the parameter
    of the same name to the :func:`ref` function.
 
    .. versionchanged:: 3.8
-      Extended the operator support on proxy objects to include the matrix
+      Extended the operator support on proxies to include the matrix
       multiplication operators ``@`` and ``@=``.
 
 
@@ -156,7 +156,7 @@ See :ref:`__slots__ documentation <slots>` for details.
 
 .. function:: getweakrefs(object)
 
-   Return a list of all weak reference and proxy objects which refer to *object*.
+   Return a list of all weak references and proxies which refer to *object*.
 
 
 .. class:: WeakKeyDictionary([dict])
@@ -171,10 +171,10 @@ See :ref:`__slots__ documentation <slots>` for details.
       Added support for ``|`` and ``|=`` operators, specified in :pep:`584`.
 
 :class:`WeakKeyDictionary` objects have an additional method that
-exposes the internal references directly.  The references are not guaranteed to
-be "live" at the time they are used, so the result of calling the references
+exposes the internal weak references directly.  The weak references are not guaranteed to
+be "live" at the time they are used, so the result of calling them
 needs to be checked before being used.  This can be used to avoid creating
-references that will cause the garbage collector to keep the keys around longer
+strong references that will cause the garbage collector to keep the keys around longer
 than needed.
 
 
@@ -207,7 +207,7 @@ objects.
    discarded when no strong reference to it exists any more.
 
 
-.. class:: WeakMethod(method)
+.. class:: WeakMethod(method[, callback])
 
    A custom :class:`ref` subclass which simulates a weak reference to a bound
    method (i.e., a method defined on a class and looked up on an instance).
@@ -233,13 +233,15 @@ objects.
       >>> r()
       >>>
 
+   *callback* is the same as the parameter of the same name to the :func:`ref` function.
+
    .. versionadded:: 3.4
 
 .. class:: finalize(obj, func, /, *args, **kwargs)
 
-   Return a callable finalizer object which will be called when *obj*
-   is garbage collected. Unlike an ordinary weak reference, a finalizer
-   will always survive until the reference object is collected, greatly
+   Return a callable finalizer which will be called when *obj*
+   is garbage collected.  Unlike an ordinary weak reference, a finalizer
+   will always survive until the referent is collected, greatly
    simplifying lifecycle management.
 
    A finalizer is considered *alive* until it is called (either explicitly
@@ -292,7 +294,7 @@ objects.
    .. note::
 
       It is important to ensure that *func*, *args* and *kwargs* do
-      not own any references to *obj*, either directly or indirectly,
+      not own any strong references to *obj*, either directly or indirectly,
       since otherwise *obj* will never be garbage collected.  In
       particular, *func* should not be a bound method of *obj*.
 
@@ -301,17 +303,17 @@ objects.
 
 .. data:: ReferenceType
 
-   The type object for weak references objects.
+   The type object for weak references.
 
 
 .. data:: ProxyType
 
-   The type object for proxies of objects which are not callable.
+   The type object for proxies to objects which are not callable.
 
 
 .. data:: CallableProxyType
 
-   The type object for proxies of callable objects.
+   The type object for proxies to callable objects.
 
 
 .. data:: ProxyTypes
@@ -333,8 +335,8 @@ objects.
 Weak Reference Objects
 ----------------------
 
-Weak reference objects have no methods and no attributes besides
-:attr:`ref.__callback__`. A weak reference object allows the referent to be
+Weak references have no methods and no attributes besides
+:attr:`ref.__callback__`.  A weak reference allows the referent to be
 obtained, if it still exists, by calling it:
 
    >>> import weakref
@@ -347,18 +349,18 @@ obtained, if it still exists, by calling it:
    >>> o is o2
    True
 
-If the referent no longer exists, calling the reference object returns
+If the referent no longer exists, calling the weak reference returns
 :const:`None`:
 
    >>> del o, o2
    >>> print(r())
    None
 
-Testing that a weak reference object is still live should be done using the
+Testing that a weak reference is still live should be done using the
 expression ``ref() is not None``.  Normally, application code that needs to use
-a reference object should follow this pattern::
+a weak reference should follow this pattern::
 
-   # r is a weak reference object
+   # r is a weak reference
    o = r()
    if o is None:
        # referent has been garbage collected
@@ -375,7 +377,7 @@ applications as well as single-threaded applications.
 Specialized versions of :class:`ref` objects can be created through subclassing.
 This is used in the implementation of the :class:`WeakValueDictionary` to reduce
 the memory overhead for each entry in the mapping.  This may be most useful to
-associate additional information with a reference, but could also be used to
+associate additional information with a weak reference, but could also be used to
 insert additional processing on calls to retrieve the referent.
 
 This example shows how a subclass of :class:`ref` can be used to store
@@ -393,7 +395,7 @@ the referent is accessed::
 
        def __call__(self):
            """Return a pair containing the referent and the number of
-           times the reference has been called.
+           times the weak reference has been called.
            """
            ob = super().__call__()
            if ob is not None:
@@ -435,8 +437,8 @@ Finalizer Objects
 -----------------
 
 The main benefit of using :class:`finalize` is that it makes it simple
-to register a callback without needing to preserve the returned finalizer
-object.  For instance
+to register a callback without needing to preserve the returned finalizer.
+For instance
 
     >>> import weakref
     >>> class Object:
@@ -492,7 +494,7 @@ is still alive.  For instance
    obj dead or exiting
 
 
-Comparing finalizers with :meth:`__del__` methods
+Comparing Finalizers with :meth:`__del__` Methods
 -------------------------------------------------
 
 Suppose we want to create a class whose instances represent temporary
@@ -531,7 +533,7 @@ However, handling of :meth:`__del__` methods is notoriously implementation
 specific, since it depends on internal details of the interpreter's garbage
 collector implementation.
 
-A more robust alternative can be to define a finalizer which only references
+A more robust alternative can be used to define a finalizer which only references
 the specific functions and objects that it needs, rather than having access
 to the full state of the object::
 
@@ -551,8 +553,8 @@ Defined like this, our finalizer only receives a reference to the details
 it needs to clean up the directory appropriately. If the object never gets
 garbage collected the finalizer will still be called at exit.
 
-The other advantage of weakref based finalizers is that they can be used to
-register finalizers for classes where the definition is controlled by a
+The other advantage of finalizers is that they can be used
+for classes where the definition is controlled by a
 third party, such as running code when a module is unloaded::
 
     import weakref, sys
@@ -563,7 +565,7 @@ third party, such as running code when a module is unloaded::
 
 .. note::
 
-   If you create a finalizer object in a daemonic thread just as the program
+   If you create a finalizer in a daemonic thread just as the program
    exits then there is the possibility that the finalizer
    does not get called at exit.  However, in a daemonic thread
    :func:`atexit.register`, ``try: ... finally: ...`` and ``with: ...``

Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst

@@ -0,0 +1,2 @@
+Document the optional *callback* parameter of :class:`WeakMethod`. Patch by
+Géry Ogam.