[Python-checkins] [3.7] bpo-40895: Update weakref documentation to remove old warnings (GH-20687) (GH-20793)

[Antoine Pitrou]

https://github.com/python/cpython/commit/049039832da3d02592d680cebf71ab8a665a6564
commit: 049039832da3d02592d680cebf71ab8a665a6564
branch: 3.7
author: Antoine Pitrou <antoine at python.org>
committer: GitHub <noreply at github.com>
date: 2020-06-10T13:37:21-07:00
summary:

[3.7] bpo-40895: Update weakref documentation to remove old warnings (GH-20687) (GH-20793)



The doccumentation at https://docs.python.org/3.10/library/weakref.html cautions that the `WeakKeyDictionary` and `WeakValueDictionary` are susceptible to the problem of dictionary mutation during iteration.

These notes present the user with a problem that has no easy solution.

I dug into the implementation and found that fortunately, Antoine Pitrou already addressed this challenge (10 years ago!) by introducing an `_IterationGuard` context manager to the implementation, which delays mutation while an iteration is in progress.

I asked for confirmation and @pitrou agreed that these notes could be removed:
https://github.com/python/cpython/commit/c1baa601e2b558deb690edfdf334fceee3b03327GH-commitcomment-39514438.
(cherry picked from commit 1642c0ef750f96664a98cadb09301d492098d2fb)

Co-authored-by: Daniel Fortunov <asqui at users.noreply.github.com>

Automerge-Triggered-By: @pitrou

files:
M Doc/library/weakref.rst

diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index 93efcef1501b4..c92abe73785fe 100644
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -159,13 +159,6 @@ Extension types can easily be made to support weak references; see
    application without adding attributes to those objects.  This can be especially
    useful with objects that override attribute accesses.
 
-   .. note::
-
-      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 by the program during iteration may cause items in the
-      dictionary to vanish "by magic" (as a side effect of garbage collection).
 
 :class:`WeakKeyDictionary` objects have an additional method that
 exposes the internal references directly.  The references are not guaranteed to
@@ -185,13 +178,6 @@ than needed.
    Mapping class that references values weakly.  Entries in the dictionary will be
    discarded when no strong reference to the value exists any more.
 
-   .. note::
-
-      Caution:  Because a :class:`WeakValueDictionary` 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:`WeakValueDictionary` because actions performed
-      by the program during iteration may cause items in the dictionary to vanish "by
-      magic" (as a side effect of garbage collection).
 
 :class:`WeakValueDictionary` objects have an additional method that has the
 same issues as the :meth:`keyrefs` method of :class:`WeakKeyDictionary`