#1918: document that weak references *to* an object are

cleared before the object's __del__ is called, to ensure that the weak
reference callback (if any) finds the object healthy.

Doc/library/weakref.rst

@@ -26,18 +26,20 @@ only remaining references to a referent are weak references,
 :term:`garbage collection` is free to destroy the referent and reuse its memory
 for something else.  A primary use for weak references is to implement caches or
 mappings holding large objects, where it's desired that a large object not be
-kept alive solely because it appears in a cache or mapping.  For example, if you
+kept alive solely because it appears in a cache or mapping.
-have a number of large binary image objects, you may wish to associate a name
+
-with each.  If you used a Python dictionary to map names to images, or images to
+For example, if you have a number of large binary image objects, you may wish to
-names, the image objects would remain alive just because they appeared as values
+associate a name with each.  If you used a Python dictionary to map names to
-or keys in the dictionaries.  The :class:`WeakKeyDictionary` and
+images, or images to names, the image objects would remain alive just because
-:class:`WeakValueDictionary` classes supplied by the :mod:`weakref` module are
+they appeared as values or keys in the dictionaries.  The
-an alternative, using weak references to construct mappings that don't keep
+:class:`WeakKeyDictionary` and :class:`WeakValueDictionary` classes supplied by
-objects alive solely because they appear in the mapping objects.  If, for
+the :mod:`weakref` module are an alternative, using weak references to construct
-example, an image object is a value in a :class:`WeakValueDictionary`, then when
+mappings that don't keep objects alive solely because they appear in the mapping
-the last remaining references to that image object are the weak references held
+objects.  If, for example, an image object is a value in a
-by weak mappings, garbage collection can reclaim the object, and its
+:class:`WeakValueDictionary`, then when the last remaining references to that
-corresponding entries in weak mappings are simply deleted.
+image object are the weak references held by weak mappings, garbage collection
+can reclaim the object, and its corresponding entries in weak mappings are
+simply deleted.
 
 :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references
 in their implementation, setting up callback functions on the weak references
@@ -48,6 +50,12 @@ own weak references directly.  The low-level machinery used by the weak
 dictionary implementations is exposed by the :mod:`weakref` module for the
 benefit of advanced uses.
 
+.. note::
+
+   Weak references to an object are cleared before the object's :meth:`__del__`
+   is called, to ensure that the weak reference callback (if any) finds the
+   object still alive.
+
 Not all objects can be weakly referenced; those objects which can include class
 instances, functions written in Python (but not in C), methods (both bound and
 unbound), sets, frozensets, file objects, :term:`generator`\s, type objects,
@@ -136,9 +144,9 @@ Extension types can easily be made to support weak references; see
 
       Caution: Because a :class:`WeakKeyDictionary` is built on top of a Python
       dictionary, it must not change size when iterating over it.  This can be
-      difficult to ensure for a :class:`WeakKeyDictionary` because actions performed
+      difficult to ensure for a :class:`WeakKeyDictionary` because actions
-      by the program during iteration may cause items in the dictionary to vanish "by
+      performed by the program during iteration may cause items in the
-      magic" (as a side effect of garbage collection).
+      dictionary to vanish "by magic" (as a side effect of garbage collection).
 
 :class:`WeakKeyDictionary` objects have the following additional methods.  These
 expose the internal references directly.  The references are not guaranteed to