gh-152132: Fix Py_RunMain() to return an exit code (GH-153446)

* Fix Py_RunMain() to return an exit code, rather than calling
  Py_Exit(), when running a script, a command, or the REPL.
* _PyRun_SimpleFile() now logs errors to stderr, for example if setting
  __main__.__file__ fails.
* Add tests on Py_RunMain() exitcode.
* Rename functions:

  * _PyRun_SimpleStringFlagsWithName() => _PyRun_SimpleString()
  * _PyRun_SimpleFileObject() => _PyRun_SimpleFile()
  * _PyRun_AnyFileObject() => _PyRun_AnyFile()
  * _PyRun_InteractiveLoopObject() => _PyRun_InteractiveLoop()

* Change _PyRun_SimpleString(), _PyRun_SimpleFile(), _PyRun_AnyFile() and
  _PyRun_InteractiveLoop() return type to PyObject*.
* pymain_repl() now displays the error if PySys_Audit() or
  import _pyrepl failed.
* PyRun_SimpleFileExFlags() and PyRun_AnyFileExFlags() now log
  PyUnicode_DecodeFSDefault() error. So these functions can no longer
  return -1 with an exception set.
(cherry picked from commit fac72f1)

Co-authored-by: Victor Stinner <vstinner@python.org>

Author: vstinner

Include/internal/pycore_pylifecycle.h

@@ -111,9 +111,6 @@ extern int _Py_LegacyLocaleDetected(int warn);
 // Export for 'readline' shared extension
 PyAPI_FUNC(char*) _Py_SetLocaleFromEnv(int category);
 
-// Export for special main.c string compiling with source tracebacks
-int _PyRun_SimpleStringFlagsWithName(const char *command, const char* name, PyCompilerFlags *flags);
-
 
 /* interpreter config */
 

Include/internal/pycore_pythonrun.h

@@ -8,23 +8,18 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-extern int _PyRun_SimpleFileObject(
+extern PyObject* _PyRun_SimpleFile(
     FILE *fp,
     PyObject *filename,
     int closeit,
     PyCompilerFlags *flags);
 
-extern int _PyRun_AnyFileObject(
+extern PyObject* _PyRun_AnyFile(
     FILE *fp,
     PyObject *filename,
     int closeit,
     PyCompilerFlags *flags);
 
-extern int _PyRun_InteractiveLoopObject(
-    FILE *fp,
-    PyObject *filename,
-    PyCompilerFlags *flags);
-
 extern int _PyObject_SupportedAsScript(PyObject *);
 extern const char* _Py_SourceAsString(
     PyObject *cmd,
@@ -39,6 +34,12 @@ extern PyObject * _Py_CompileStringObjectWithModule(
     PyCompilerFlags *flags, int optimize,
     PyObject *module);
 
+// Export for special main.c string compiling with source tracebacks
+extern PyObject* _PyRun_SimpleString(
+    const char *command,
+    PyObject* name,
+    PyCompilerFlags *flags);
+
 
 /* Stack size, in "pointers". This must be large enough, so
  * no two calls to check recursion depth are more than this far

Lib/test/test_embed.py

@@ -68,6 +68,9 @@
 if not os.path.isfile(os.path.join(STDLIB_INSTALL, 'os.py')):
     STDLIB_INSTALL = None
 
+CODE_EXITCODE_123 = 'raise SystemExit(123)'
+
+
 def debug_build(program):
     program = os.path.basename(program)
     name = os.path.splitext(program)[0]
@@ -117,12 +120,16 @@ def run_embedded_interpreter(self, *args, env=None,
             env = env.copy()
             env['SYSTEMROOT'] = os.environ['SYSTEMROOT']
 
-        p = subprocess.Popen(cmd,
-                             stdout=subprocess.PIPE,
-                             stderr=subprocess.PIPE,
-                             universal_newlines=True,
-                             env=env,
-                             cwd=cwd)
+        kwargs = dict(
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            universal_newlines=True,
+            env=env,
+            cwd=cwd,
+        )
+        if input is not None:
+            kwargs['stdin'] = subprocess.PIPE
+        p = subprocess.Popen(cmd, **kwargs)
         try:
             (out, err) = p.communicate(input=input, timeout=timeout)
         except:
@@ -565,6 +572,55 @@ def _nogil_filtered_err(err: str, mod_name: str) -> str:
         ]
         return "\n".join(filtered_err_lines)
 
+    def check_program_exitcode(self, *args, check_stderr=True, **kwargs):
+        out, err = self.run_embedded_interpreter(*args, **kwargs)
+        self.assertEqual(out.rstrip(), 'ok! Py_RunMain() returned 123')
+        if check_stderr:
+            self.assertEqual(err, '')
+
+    def test_init_run_main_code_exitcode(self):
+        code = CODE_EXITCODE_123
+        self.check_program_exitcode("test_init_run_main_code_exitcode", code)
+
+    def test_init_run_main_script_exitcode(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            filename = os.path.join(tmpdir, 'script.py')
+            with open(filename, 'w') as fp:
+                fp.write(CODE_EXITCODE_123)
+
+            self.check_program_exitcode("test_init_run_main_script_exitcode",
+                                        filename)
+
+    def test_init_run_main_interactive_exitcode(self):
+        code = CODE_EXITCODE_123
+        self.check_program_exitcode("test_init_run_main_interactive_exitcode",
+                                    input=code,
+                                    check_stderr=False)
+
+    def test_init_run_main_startup_exitcode(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            filename = os.path.join(tmpdir, 'startup.py')
+            with open(filename, 'x') as fp:
+                fp.write(CODE_EXITCODE_123)
+
+            env = dict(os.environ)
+            env['PYTHONSTARTUP'] = filename
+            self.check_program_exitcode("test_init_run_main_interactive_exitcode",
+                                        env=env,
+                                        check_stderr=False)
+
+    def test_init_run_main_module_exitcode(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            modname = '_testembed_testmodule'
+            filename = os.path.join(tmpdir, modname + '.py')
+            with open(filename, 'x', encoding='utf8') as fp:
+                fp.write(CODE_EXITCODE_123)
+
+            env = dict(os.environ)
+            env['PYTHONPATH'] = tmpdir
+            self.check_program_exitcode("test_init_run_main_module_exitcode",
+                                        modname, env=env)
+
 
 def config_dev_mode(preconfig, config):
     preconfig['allocator'] = PYMEM_ALLOCATOR_DEBUG

Misc/NEWS.d/next/C_API/2026-07-09-17-33-29.gh-issue-152132.Ma8MJZ.rst

@@ -0,0 +1,3 @@
+Fix :c:func:`Py_RunMain` to return an exit code, rather than calling
+:c:func:`Py_Exit`, when running a script, a command, or the REPL. Patch by
+Victor Stinner.

Modules/_testcapi/run.c

@@ -129,9 +129,6 @@ run_simplefile(PyObject *mod, PyObject *args)
     assert(_Py_IsValidFD(fd));
     fclose(fp);
 
-    if (res == -1 && PyErr_Occurred()) {
-        return NULL;
-    }
     assert(!PyErr_Occurred());
     return PyLong_FromLong(res);
 }
@@ -203,9 +200,6 @@ run_simplefileex(PyObject *mod, PyObject *args)
         return NULL;
     }
 
-    if (res == -1 && PyErr_Occurred()) {
-        return NULL;
-    }
     assert(!PyErr_Occurred());
     return PyLong_FromLong(res);
 }
@@ -243,9 +237,6 @@ run_simplefileexflags(PyObject *mod, PyObject *args)
         return NULL;
     }
 
-    if (res == -1 && PyErr_Occurred()) {
-        return NULL;
-    }
     assert(!PyErr_Occurred());
     return PyLong_FromLong(res);
 }
@@ -272,9 +263,6 @@ run_anyfile(PyObject *mod, PyObject *args)
     assert(_Py_IsValidFD(fd));
     fclose(fp);
 
-    if (res == -1 && PyErr_Occurred()) {
-        return NULL;
-    }
     assert(!PyErr_Occurred());
     return PyLong_FromLong(res);
 }
@@ -310,9 +298,6 @@ run_anyfileflags(PyObject *mod, PyObject *args)
     assert(_Py_IsValidFD(fd));
     fclose(fp);
 
-    if (res == -1 && PyErr_Occurred()) {
-        return NULL;
-    }
     assert(!PyErr_Occurred());
     return PyLong_FromLong(res);
 }
@@ -342,9 +327,6 @@ run_anyfileex(PyObject *mod, PyObject *args)
         return NULL;
     }
 
-    if (res == -1 && PyErr_Occurred()) {
-        return NULL;
-    }
     assert(!PyErr_Occurred());
     return PyLong_FromLong(res);
 }
@@ -382,9 +364,6 @@ run_anyfileexflags(PyObject *mod, PyObject *args)
         return NULL;
     }
 
-    if (res == -1 && PyErr_Occurred()) {
-        return NULL;
-    }
     assert(!PyErr_Occurred());
     return PyLong_FromLong(res);
 }
@@ -664,9 +643,6 @@ run_simplestring(PyObject *mod, PyObject *args)
     }
 
     int res = PyRun_SimpleString(str);
-    if (res == -1 && PyErr_Occurred()) {
-        return NULL;
-    }
     assert(!PyErr_Occurred());
     return PyLong_FromLong(res);
 }
@@ -689,9 +665,6 @@ run_simplestringflags(PyObject *mod, PyObject *args)
     }
 
     int res = PyRun_SimpleStringFlags(str, pflags);
-    if (res == -1 && PyErr_Occurred()) {
-        return NULL;
-    }
     assert(!PyErr_Occurred());
     return PyLong_FromLong(res);
 }