gh-158080: Py_InitializeFromConfig() no longer exits Python (#158085)

If a command line option wants to exit Python, move this option
processing from PyConfig_Read() to Py_Main(). So
Py_InitializeFromInitConfig() and Py_InitializeFromConfig() can no
longer return an exit code.

Deprecate PyInitConfig_GetExitCode(), PyStatus_Exit(), and PyStatus_IsExit()
functions, and PyStatus.exitcode member.

Renumber getopt.c long options to start at 1, instead of 0.

Author: vstinner

Doc/c-api/init_config.rst

@@ -116,15 +116,14 @@ Error Handling
 
    Get the *config* exit code.
 
-   * Set *\*exitcode* and return ``1`` if *config* has an exit code set.
-   * Return ``0`` if *config* has no exit code set.
+   Return ``0`` and leave *\*exitcode* unchanged.
 
-   Only the ``Py_InitializeFromInitConfig()`` function can set an exit
-   code if the ``parse_argv`` option is non-zero.
+   In Python 3.15, :c:func:`Py_InitializeFromInitConfig` sets an exit code if a
+   command line option wants to exit Python. This is no longer the case in
+   Python 3.16. Instead, the option is now processed in :c:func:`Py_RunMain`.
+   This function became useless.
 
-   An exit code can be set when parsing the command line failed (exit
-   code ``2``) or when a command line option asks to display the command
-   line help (exit code ``0``).
+   .. deprecated:: next
 
 
 Get Options
@@ -247,10 +246,11 @@ Initialize Python
 
    * Return ``0`` on success.
    * Set an error in *config* and return ``-1`` on error.
-   * Set an exit code in *config* and return ``-1`` if Python wants to
-     exit.
 
-   See ``PyInitConfig_GetExitcode()`` for the exit code case.
+   .. versionchanged:: next
+      The function no longer sets an exit code if a command line option wants
+      to exit Python. Instead, the option is now processed in
+      :c:func:`Py_RunMain`.
 
 
 .. _pyinitconfig-opts:
@@ -690,9 +690,6 @@ Example of customized Python always running in isolated mode::
 
     exception:
         PyConfig_Clear(&config);
-        if (PyStatus_IsExit(status)) {
-            return status.exitcode;
-        }
         /* Display the error message and exit the process with
            non-zero exit code */
         Py_ExitStatusException(status);
@@ -758,6 +755,8 @@ PyStatus
 
       Exit code. Argument passed to ``exit()``.
 
+      .. deprecated:: next
+
    .. c:member:: const char *err_msg
 
       Error message.
@@ -788,6 +787,11 @@ PyStatus
 
       Exit Python with the specified exit code.
 
+      .. deprecated:: next
+         :c:func:`Py_InitializeFromConfig` no longer sets an exit code if a
+         command line option wants to exit Python. Instead, the option is
+         now processed in :c:func:`Py_RunMain`.
+
    Functions to handle a status:
 
    .. c:function:: int PyStatus_Exception(PyStatus status)
@@ -803,6 +807,11 @@ PyStatus
 
       Is the result an exit?
 
+      .. deprecated:: next
+         :c:func:`Py_InitializeFromConfig` no longer sets an exit code if a
+         command line option wants to exit Python. Instead, the option is
+         now processed in :c:func:`Py_RunMain`.
+
    .. c:function:: void Py_ExitStatusException(PyStatus status)
 
       Call ``exit(exitcode)`` if *status* is an exit. Print the error

Doc/c-api/interp-lifecycle.rst

@@ -127,6 +127,11 @@ Initializing and finalizing the interpreter
    interpreter, populating the runtime configuration structure, and querying
    the returned status structure.
 
+   .. versionchanged:: next
+      The function no longer returns an exit code if a command line option
+      wants to exit Python. Instead, the option is processed in
+      :c:func:`Py_RunMain`.
+
 
 .. c:function:: int Py_IsInitialized()
 

Doc/whatsnew/3.16.rst

@@ -1128,6 +1128,14 @@ Deprecated C APIs
   and :c:func:`PyAsyncGen_New` are deprecated.
   They are scheduled for removal in 3.18.
 
+* Deprecate :c:func:`PyInitConfig_GetExitCode`, :c:func:`PyStatus_Exit`,
+  and :c:func:`PyStatus_IsExit` functions, and :c:member:`PyStatus.exitcode`
+  member. :c:func:`Py_InitializeFromInitConfig` and
+  :c:func:`Py_InitializeFromConfig` can no longer return an exit code.
+  Instead, if a command line option wants to exit Python, the option is
+  now processed in :c:func:`Py_RunMain`.
+  (Contributed by Victor Stinner in :gh:`158080`.)
+
 * :c:func:`PyModule_GetFilename` is no longer deprecated, but using
   :c:func:`PyModule_GetFilenameObject` instead is still recommended.
   (Contributed by Victor Stinner in :gh:`154757`.)

Include/cpython/initconfig.h

@@ -11,19 +11,19 @@ typedef struct {
     enum {
         _PyStatus_TYPE_OK=0,
         _PyStatus_TYPE_ERROR=1,
-        _PyStatus_TYPE_EXIT=2
+        _PyStatus_TYPE_EXIT=2  // deprecated
     } _type;
     const char *func;
     const char *err_msg;
-    int exitcode;
+    Py_DEPRECATED(3.16) int exitcode;
 } PyStatus;
 
 PyAPI_FUNC(PyStatus) PyStatus_Ok(void);
 PyAPI_FUNC(PyStatus) PyStatus_Error(const char *err_msg);
 PyAPI_FUNC(PyStatus) PyStatus_NoMemory(void);
-PyAPI_FUNC(PyStatus) PyStatus_Exit(int exitcode);
+Py_DEPRECATED(3.16) PyAPI_FUNC(PyStatus) PyStatus_Exit(int exitcode);
 PyAPI_FUNC(int) PyStatus_IsError(PyStatus err);
-PyAPI_FUNC(int) PyStatus_IsExit(PyStatus err);
+Py_DEPRECATED(3.16) PyAPI_FUNC(int) PyStatus_IsExit(PyStatus err);
 PyAPI_FUNC(int) PyStatus_Exception(PyStatus err);
 
 /* --- PyWideStringList ------------------------------------------------ */
@@ -242,6 +242,11 @@ typedef struct PyConfig {
     // PYTHON_PRESITE=package.module or -X presite=package.module
     wchar_t *run_presite;
 #endif
+
+    // If a command line option wants to exit Python, store it in this member
+    // and only process the option in Py_RunMain() instead of PyConfig_Read().
+    // If equals to 0, there is no option.
+    int _deferred_cmdline_option;
 } PyConfig;
 
 PyAPI_FUNC(void) PyConfig_InitPythonConfig(PyConfig *config);
@@ -293,7 +298,7 @@ PyAPI_FUNC(void) PyInitConfig_Free(PyInitConfig *config);
 
 PyAPI_FUNC(int) PyInitConfig_GetError(PyInitConfig* config,
     const char **err_msg);
-PyAPI_FUNC(int) PyInitConfig_GetExitCode(PyInitConfig* config,
+Py_DEPRECATED(3.16) PyAPI_FUNC(int) PyInitConfig_GetExitCode(PyInitConfig* config,
     int *exitcode);
 
 PyAPI_FUNC(int) PyInitConfig_HasOption(PyInitConfig *config,

Include/internal/pycore_initconfig.h

@@ -182,6 +182,8 @@ extern PyObject* _PyConfig_CreateXOptionsDict(const PyConfig *config);
 
 extern void _Py_DumpPathConfig(PyThreadState *tstate);
 
+extern int _PyConfig_ProcessDeferredCmdlineOption(PyConfig *config);
+
 
 /* --- Function used for testing ---------------------------------- */
 

Lib/test/test_cmd_line.py

@@ -133,11 +133,16 @@ def test_site_flag(self):
 
     @support.cpython_only
     def test_version(self):
-        version = ('Python %d.%d' % sys.version_info[:2]).encode("ascii")
-        for switch in '-V', '--version', '-VV':
-            rc, out, err = assert_python_ok(switch)
-            self.assertNotStartsWith(err, version)
-            self.assertStartsWith(out, version)
+        short_version = ('Python %d.%d' % sys.version_info[:2])
+        for switch in ('-V', '--version'):
+            with self.subTest(switch=switch):
+                rc, out, err = assert_python_ok(switch)
+                self.assertStartsWith(out, short_version.encode())
+                self.assertEqual(err, b'')
+
+        rc, out, err = assert_python_ok('-VV')
+        self.assertEqual(out.rstrip(), f"Python {sys.version}".encode())
+        self.assertEqual(err, b'')
 
     def test_verbose(self):
         # -v causes imports to write to stderr.  If the write to

Lib/test/test_embed.py

@@ -783,6 +783,7 @@ class InitConfigTests(EmbeddingTestsMixin, unittest.TestCase):
         'use_frozen_modules': not support.Py_DEBUG,
         'safe_path': False,
         '_is_python_build': IGNORE_CONFIG,
+        '_deferred_cmdline_option': 0,
     }
     if Py_STATS:
         CONFIG_COMPAT['_pystats'] = False

Misc/NEWS.d/next/C_API/2026-09-24-15-27-35.gh-issue-158080.YIqypf.rst

@@ -0,0 +1,6 @@
+Deprecate :c:func:`PyInitConfig_GetExitCode`, :c:func:`PyStatus_Exit`, and
+:c:func:`PyStatus_IsExit` functions, and :c:member:`PyStatus.exitcode`
+member. :c:func:`Py_InitializeFromInitConfig` and
+:c:func:`Py_InitializeFromConfig` can no longer return an exit code.
+Instead, if a command line option wants to exit Python, the option is
+now processed in :c:func:`Py_RunMain`. Patch by Victor Stinner.

Modules/main.c

@@ -749,13 +749,21 @@ pymain_set_path0(PyObject *main_importer_path)
 static void
 pymain_run_python(int *exitcode)
 {
-    int set_running_main = 0;
-
-    PyObject *main_importer_path = NULL;
     PyInterpreterState *interp = _PyInterpreterState_GET();
     /* pymain_repl() and pymain_run_stdin() modify the config */
     PyConfig *config = (PyConfig*)_PyInterpreterState_GetConfig(interp);
 
+    // Process command line options which want to exit Python
+    int cmdline_exitcode = _PyConfig_ProcessDeferredCmdlineOption(config);
+    if (cmdline_exitcode >= 0) {
+        *exitcode = cmdline_exitcode;
+        return;
+    }
+
+    int set_running_main = 0;
+
+    PyObject *main_importer_path = NULL;
+
     /* ensure path config is written into global variables */
     PyStatus status = _PyPathConfig_UpdateGlobal(config);
     if (_PyStatus_EXCEPTION(status)) {
@@ -910,10 +918,7 @@ static int
 pymain_main(_PyArgv *args)
 {
     PyStatus status = pymain_init(args);
-    if (_PyStatus_IS_EXIT(status)) {
-        pymain_free();
-        return status.exitcode;
-    }
+    assert(!_PyStatus_IS_EXIT(status));
     if (_PyStatus_EXCEPTION(status)) {
         pymain_exit_error(status);
     }

Programs/_bootstrap_python.c

@@ -104,9 +104,6 @@ main(int argc, char **argv)
 
 error:
     PyConfig_Clear(&config);
-    if (PyStatus_IsExit(status)) {
-        return status.exitcode;
-    }
     Py_ExitStatusException(status);
 }