One small round of cleanup.

Author: warsaw

Lib/site.py

@@ -164,7 +164,7 @@ def _init_pathinfo():
 # addsitedir() calls which use the default defer_processing_start_files=False
 # are self-contained: they create a per-call _StartupState, populate it from
 # the site directory's .pth/.start files, run process() on it, and then throw
-# the state it away.  This is implicit batching and in that case the
+# the state away.  This is implicit batching and in that case the
 # _startup_state global variable stays None.
 #
 # main() needs different semantics: it accumulates state across multiple
@@ -369,10 +369,10 @@ def _extend_syspath(self):
                     )
 
     def _exec_imports(self):
-        # For each `import` line we've seen in a .pth file, exec() it in order
-        # — unless the .pth has a matching .start file in this same batch, in
-        # which case PEP 829 says the import lines are suppressed in favor of
-        # the .start's entry points.
+        # For each `import` line we've seen in a .pth file, exec() it in
+        # order, unless the .pth has a matching .start file in this same
+        # batch.  In that case, PEP 829 says the import lines are
+        # suppressed in favor of the .start's entry points.
         for filename, imports in self._importexecs.items():
             # Given "/path/to/foo.pth", check whether "/path/to/foo.start" was
             # registered in this same batch.
@@ -446,7 +446,7 @@ def process_startup_files():
     *before* state.process() runs.  This way, if an exec'd import line
     or .start entry point itself calls site.addsitedir(), that call
     creates its own per-call _StartupState rather than mutating the dicts
-    being iterated here — see gh-149504.
+    being iterated here.  See gh-149504.
     """
     global _startup_state
     if _startup_state is None:
@@ -508,7 +508,7 @@ def addsitedir(sitedir, known_paths=None, *, defer_processing_start_files=False)
         # 1. A batch is already active (_startup_state is set, e.g.  because
         #    main() previously called us with
         #    defer_processing_start_files=True).  Participate in this batch by
-        #    sharing the same.  Don't flush the state since the batch's
+        #    sharing the same state.  Don't flush the state since the batch's
         #    eventual process_startup_files() will do that.
         #
         # 2. There is no active batch but the caller passed

Lib/test/test_site.py

@@ -1606,9 +1606,9 @@ def increment():
 
     # gh-149504
     def test_reentrant_addsitedir_pth(self):
-        # An import line in a .pth file that calls site.addsitedir() must
-        # not crash or re-execute outer entries while the outer
-        # _exec_imports() is iterating _pending_importexecs.
+        # An import line in a .pth file that calls site.addsitedir()
+        # must not crash or re-execute outer entries while the outer
+        # call is still processing its pending startup state.
         overlay = self.enterContext(os_helper.temp_dir())
         overlay_pth = os.path.join(overlay, 'overlay.pth')
         pkgdir = self.enterContext(os_helper.temp_dir())
@@ -1622,9 +1622,8 @@ def test_reentrant_addsitedir_pth(self):
     # gh-149504
     def test_reentrant_addsitedir_start(self):
         # As above, but the re-entry happens from a .start entry point
-        # instead of a .pth import line.  _execute_start_entrypoints()
-        # iterates _pending_entrypoints with the same pattern and is
-        # vulnerable to the same dictionary-changed-during-iteration bug.
+        # instead of a .pth import line.  The entry point execution
+        # phase is vulnerable to the same class of bug.
         overlay = self.enterContext(os_helper.temp_dir())
         overlay_pth = os.path.join(overlay, 'overlay.pth')
         pkgdir = self.enterContext(os_helper.temp_dir())

Misc/NEWS.d/next/Core_and_Builtins/2026-05-10-23-51-23.gh-issue-149504.pDSCbn.rst

@@ -0,0 +1,5 @@
+Fix :func:`site.addsitedir` to allow re-entrant calls from within startup
+files.  Previously, a ``.pth`` file containing an ``import`` line that
+called :func:`site.addsitedir` (or a ``.start`` entry point doing the same)
+could crash with ``RuntimeError: dictionary changed size during iteration``
+during site initialization, breaking tools such as ``uv run --with``.