Clean up the builtin exec() comparison section.

python · ericsnowcurrently · Nov 28, 2023 · Nov 3, 2023 · Nov 7, 2023 · Nov 7, 2023
commit 309e8267b913639cd415dba80ca7a70ccb47237a
@@ -304,40 +304,33 @@ Comparison with builtins.exec()
 
 ``Interpreter.exec()`` is essentially the same as the builtin
 ``exec()``, except it targets a different interpreter, using that
-interpreter's isolated state.
-
-The builtin ``exec()`` runs in the current OS thread and pauses
-whatever was running there, which resumes when ``exec()`` finishes.
-No other threads are affected.  (To avoid pausing the current thread,
-run ``exec()`` in a ``threading.Thread``.)
-
-``Interpreter.exec()`` works the same way.
-
-The builtin ``exec()`` executes against a namespace, by default the
-``__dict__`` of the current module (i.e. ``globals()``).
-It uses that namespace as-is and does not clear it before or after.
-
-``Interpreter.exec()`` works the same way.
-
-...where the "current" module is always the ``__main__`` module
-of the target interpreter.  This is the same as how it works
-for code run from the Python command-line (e.g. ``-m``) or the REPL.
-
-The builtin ``exec()`` discards any object returned from the
-executed code.
-
-``Interpreter.exec()`` works the same way.
-
-The builtin ``exec()`` propagates any uncaught exception from the code
-it ran.  The exception is raised from the ``exec()`` call in the
-thread that originally called ``exec()``.
-
-``Interpreter.exec()`` works the same way.
-
-...with one slight difference.  Rather than propagate the uncaught
-exception directly, we raise an ``interpreters.RunFailedError``
-with a snapshot of the uncaught exception (including its traceback)
-as the ``__cause__``.  Directly raising (a proxy of) the exception
+interpreter's distinct runtime state.
+
+Here are the relevant characteristics of the builtin ``exec()``,
+for comparison:
+
+* It runs in the current OS thread and pauses whatever was running there,
+  which resumes when ``exec()`` finishes.  No other threads are affected.
+  (To avoid pausing the current thread, run ``exec()``
+  in a ``threading.Thread``.)
+* It executes against a namespace, by default the ``__dict__`` of the
+  current module (i.e. ``globals()``).  It uses that namespace as-is
+  and does not clear it before or after.
+* When code is run from the command-line (e.g. ``-m``) or the REPL,
+  the "current" module is always the ``__main__`` module
+  of the target (main) interpreter.
+* It discards any object returned from the executed code.
+* It propagates any uncaught exception from the code it ran.
+  The exception is raised from the ``exec()`` call in the thread
+  that originally called ``exec()``.
+
+The only difference is that, rather than propagate the uncaught
+exception directly, ``Interpreter.exec()`` raises an
+``interpreters.RunFailedError`` with a snapshot
+(``traceback.TracebackException``) of the uncaught exception
+(including its traceback) as the ``__cause__``.
+
+Directly raising (a proxy of) the exception
 is problematic since it's harder to distinguish between an error
 in the ``Interpreter.exec()`` call and an uncaught exception
 from the subinterpreter.