From e12d7f60c61e9ede79adae4d440f14b7d34745f6 Mon Sep 17 00:00:00 2001 From: Daniel Fortunov Date: Wed, 10 Jun 2020 21:26:49 +0100 Subject: [PATCH] [3.8] bpo-40895: Update weakref documentation to remove old warnings (GH-20687) 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 --- Doc/library/weakref.rst | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 2dbe5e33bd0117..0d9f21d2e83a4c 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -163,13 +163,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 @@ -189,13 +182,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`