[Python-checkins] bpo-45353: Remind sys.modules users to copy when iterating. (GH-28842)

[miss-islington]

https://github.com/python/cpython/commit/459a4db5eae1f5ef063b34c61cc099820aa9ed0a
commit: 459a4db5eae1f5ef063b34c61cc099820aa9ed0a
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2021-10-09T12:54:20-07:00
summary:

bpo-45353: Remind sys.modules users to copy when iterating. (GH-28842)


This is true of all dictionaries in Python, but this one tends to
catch people off guard as they don't realize when sys.modules might
change out from underneath them as a hidden side effect of their
code.  Copying it first avoids the RuntimeError.  An example when
this happens in single threaded code are codecs being loaded which
are an implicit time of use import that most need not think about.
(cherry picked from commit 3d1ca867ed0e3ae343166806f8ddd9739e568ab4)

Co-authored-by: Gregory P. Smith <greg at krypto.org>

files:
M Doc/library/sys.rst

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index ec12e02fb37d4..8b3c6fd762731 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -1073,7 +1073,11 @@ always available.
    This is a dictionary that maps module names to modules which have already been
    loaded.  This can be manipulated to force reloading of modules and other tricks.
    However, replacing the dictionary will not necessarily work as expected and
-   deleting essential items from the dictionary may cause Python to fail.
+   deleting essential items from the dictionary may cause Python to fail.  If
+   you want to iterate over this global dictionary always use
+   ``sys.modules.copy()`` or ``tuple(sys.modules)`` to avoid exceptions as its
+   size may change during iteration as a side effect of code or activity in
+   other threads.
 
 
 .. data:: orig_argv