From 972aba86ede0bf254e16a760639a1ff8df298578 Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Wed, 10 Jun 2020 22:38:42 +0200 Subject: [3.8] bpo-40895: Update weakref documentation to remove old warnings (GH-20687) (GH-20792) 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 Automerge-Triggered-By: @pitrou --- Doc/library/weakref.rst | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 2dbe5e3..0d9f21d 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` -- cgit v0.12