[Python-checkins] bpo-40895: Update weakref documentation to remove old warnings (GH-20687)
Daniel Fortunov
webhook-mailer at python.org
Wed Jun 10 16:26:58 EDT 2020
https://github.com/python/cpython/commit/1642c0ef750f96664a98cadb09301d492098d2fb
commit: 1642c0ef750f96664a98cadb09301d492098d2fb
branch: master
author: Daniel Fortunov <asqui at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2020-06-10T13:26:49-07:00
summary:
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/c1baa601e2b558deb690edfdf334fceee3b03327#commitcomment-39514438
files:
M Doc/library/weakref.rst
diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index 12eb985c34435..d3c3a070f38af 100644
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -163,14 +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).
-
.. versionchanged:: 3.9
Added support for ``|`` and ``|=`` operators, specified in :pep:`584`.
@@ -192,14 +184,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).
-
.. versionchanged:: 3.9
Added support for ``|`` and ``|=`` operators, as specified in :pep:`584`.
More information about the Python-checkins
mailing list