PEP 587: Add Py_RunMain()

pep-0587.rst

@@ -49,7 +49,7 @@ New structures (4):
 * ``PyPreConfig``
 * ``PyWideCharList``
 
-New functions (8):
+New functions (9):
 
 * ``Py_PreInitialize(config)``
 * ``Py_PreInitializeFromArgs(config, argc, argv)``
@@ -59,6 +59,8 @@ New functions (8):
 * ``Py_InitializeFromWideArgs(config, argc, argv)``
 * ``Py_UnixMain(argc, argv)``
 * ``Py_ExitInitError(err)``
+* ``Py_RunMain()``
+
 
 New macros (6):
 
@@ -71,7 +73,9 @@ New macros (6):
 
 This PEP also adds ``_PyRuntimeState.preconfig`` (``PyPreConfig``) and
 ``PyInterpreterState.config`` (``PyConfig``) fields to these internal
-structures. They become the new reference configuration.
+structures. ``PyInterpreterState.config`` becomes the new reference
+configuration, replacing global configuration variables (and a few other
+private variables).
 
 
 PyWideCharList
@@ -303,8 +307,8 @@ There are also private fields which are for internal-usage only:
 * ``_init_main``
 * ``_install_importlib``
 
-New Py_UnixMain() function
---------------------------
+Py_UnixMain()
+-------------
 
 Python 3.7 provides a high-level ``Py_Main()`` function which requires
 to pass command line arguments as ``wchar_t*`` strings. It is
@@ -316,6 +320,38 @@ arguments as bytes::
 
     int Py_UnixMain(int argc, char **argv)
 
+Py_RunMain()
+------------
+
+The new ``Py_RunMain()`` function executes the command
+(``PyConfig.run_command``), the script (``PyConfig.run_filename``) or
+the module (``PyConfig.run_module``) specified on the command line or in
+the configuration, and then finalizes Python. It returns an exit status
+that can be passed to the ``exit()`` function.
+
+Example of custom Python executable always running in isolated mode::
+
+    #include <Python.h>
+
+    int main(int argc, char *argv[])
+    {
+        PyConfig config = PyConfig_INIT;
+        config.isolated = 1;
+
+        PyInitError err = Py_InitializeFromArgs(&config, argc, argv);
+        if (Py_INIT_FAILED(err)) {
+            Py_ExitInitError(err);
+        }
+
+        /* put more configuration code here if needed */
+
+        return Py_RunMain();
+    }
+
+The example is a basic implementation of the "System Python Executable"
+discussed in PEP 432.
+
+
 Memory allocations and Py_DecodeLocale()
 ----------------------------------------