pythongh-107954: Add PyInitConfig C API

Add PyInitConfig functions:

* PyInitConfig_Python_New()
* PyInitConfig_Isolated_New()
* PyInitConfig_Free(config)
* PyInitConfig_SetInt(config, key, value)
* PyInitConfig_SetStr(config, key, value)
* PyInitConfig_SetWStr(config, key, value)
* PyInitConfig_SetStrList(config, key, length, items)
* PyInitConfig_SetWStrList(config, key, length, items)
* PyInitConfig_GetErrorMsg(config)

Add also functions using it:

* Py_InitializeFromInitConfig(config)
* Py_ExitWithInitConfig(config)

Changes:

* Add Include/initconfig.h header.

Include/Python.h

@@ -82,7 +82,7 @@
 #include "sliceobject.h"
 #include "cpython/cellobject.h"
 #include "iterobject.h"
-#include "cpython/initconfig.h"
+#include "initconfig.h"
 #include "pystate.h"
 #include "cpython/genobject.h"
 #include "descrobject.h"

Include/cpython/initconfig.h

@@ -1,8 +1,5 @@
-#ifndef Py_PYCORECONFIG_H
-#define Py_PYCORECONFIG_H
-#ifndef Py_LIMITED_API
-#ifdef __cplusplus
-extern "C" {
+#ifndef Py_CPYTHON_INITCONFIG_H
+#  error "this header file must not be included directly"
 #endif
 
 /* --- PyStatus ----------------------------------------------- */
@@ -252,9 +249,3 @@ PyAPI_FUNC(PyStatus) PyConfig_SetWideStringList(PyConfig *config,
 
    See also PyConfig.orig_argv. */
 PyAPI_FUNC(void) Py_GetArgcArgv(int *argc, wchar_t ***argv);
-
-#ifdef __cplusplus
-}
-#endif
-#endif /* !Py_LIMITED_API */
-#endif /* !Py_PYCORECONFIG_H */

Include/initconfig.h

@@ -0,0 +1,92 @@
+#ifndef Py_INITCONFIG_H
+#define Py_INITCONFIG_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct PyInitConfig PyInitConfig;
+
+// Create a new initialization configuration.
+// It must be freed by PyInitConfig_Free().
+// Return NULL on memory allocation failure.
+//
+// PyInitConfig_Python_New() has a Python configuration by default.
+// PyInitConfig_Isolated_New() has an Isolated configuration by default.
+PyAPI_FUNC(PyInitConfig*) PyInitConfig_Python_New(void);
+PyAPI_FUNC(PyInitConfig*) PyInitConfig_Isolated_New(void);
+
+// Free memory of a initialization configuration.
+PyAPI_FUNC(void) PyInitConfig_Free(PyInitConfig *config);
+
+// Set an integer configuration option.
+// Return 0 on success, or return -1 on error.
+PyAPI_FUNC(int) PyInitConfig_SetInt(
+    PyInitConfig *config,
+    const char *key,
+    int64_t value);
+
+// Set a string configuration option from a bytes string.
+//
+// The bytes string is decoded by Py_DecodeLocale(). Preinitialize Python if
+// needed to ensure that encodings are properly configured.
+//
+// Return 0 on success, or return -1 on error.
+PyAPI_FUNC(int) PyInitConfig_SetStr(
+    PyInitConfig *config,
+    const char *key,
+    const char *value);
+
+// Set a string configuration option from a wide string.
+// Preinitialize Python if needed.
+// Return 0 on success, or return -1 on error.
+PyAPI_FUNC(int) PyInitConfig_SetWStr(
+    PyInitConfig *config,
+    const char *key,
+    const wchar_t *value);
+
+// Set a string list configuration option from bytes strings.
+//
+// The bytes strings are decoded by Py_DecodeLocale(). Preinitialize Python if
+// needed to ensure that encodings are properly configured.
+//
+// Return 0 on success, or return -1 on error.
+PyAPI_FUNC(int) PyInitConfig_SetStrList(
+    PyInitConfig *config,
+    const char *key,
+    size_t length,
+    char * const *items);
+
+// Set a string list configuration option from a wide strings.
+// Preinitialize Python if needed.
+// Return 0 on success, or return -1 on error.
+PyAPI_FUNC(int) PyInitConfig_SetWStrList(
+    PyInitConfig *config,
+    const char *key,
+    size_t length,
+    wchar_t * const *items);
+
+// Initialize Python from the initialization configuration.
+// Return 0 on success.
+// Return -1 if Python wants to exit and on error
+PyAPI_FUNC(int) Py_InitializeFromInitConfig(PyInitConfig *config);
+
+// Get the current error message.
+// Return a UTF-8 string allocated by malloc(). It must be released by free().
+// Return NULL on memory allocation failure.
+PyAPI_FUNC(char*) PyInitConfig_GetErrorMsg(PyInitConfig* config);
+
+// Exit Python and free memory of a initialization configuration.
+// The function does not return.
+PyAPI_FUNC(void) _Py_NO_RETURN Py_ExitWithInitConfig(PyInitConfig *config);
+
+
+#ifndef Py_LIMITED_API
+#  define Py_CPYTHON_INITCONFIG_H
+#  include "cpython/initconfig.h"
+#  undef Py_CPYTHON_INITCONFIG_H
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+#endif   // !Py_INITCONFIG_H

Include/internal/pycore_initconfig.h

@@ -62,6 +62,10 @@ extern int _PyWideStringList_Copy(PyWideStringList *list,
 extern PyStatus _PyWideStringList_Extend(PyWideStringList *list,
     const PyWideStringList *list2);
 extern PyObject* _PyWideStringList_AsList(const PyWideStringList *list);
+extern PyStatus _PyWideStringList_FromBytes(
+    PyWideStringList *list,
+    Py_ssize_t length,
+    char * const *items);
 
 
 /* --- _PyArgv ---------------------------------------------------- */

Lib/test/test_embed.py

@@ -393,6 +393,14 @@ def test_ucnhash_capi_reset(self):
         out, err = self.run_embedded_interpreter("test_repeated_init_exec", code)
         self.assertEqual(out, '9\n' * INIT_LOOPS)
 
+
+def config_dev_mode(preconfig, config):
+    preconfig['allocator'] = PYMEM_ALLOCATOR_DEBUG
+    config['dev_mode'] = 1
+    config['warnoptions'] = ['default']
+    config['faulthandler'] = 1
+
+
 class InitConfigTests(EmbeddingTestsMixin, unittest.TestCase):
     maxDiff = 4096
     UTF8_MODE_ERRORS = ('surrogatepass' if MS_WINDOWS else 'surrogateescape')
@@ -510,7 +518,7 @@ class InitConfigTests(EmbeddingTestsMixin, unittest.TestCase):
         'check_hash_pycs_mode': 'default',
         'pathconfig_warnings': 1,
         '_init_main': 1,
-        'use_frozen_modules': not support.Py_DEBUG,
+        'use_frozen_modules': int(not support.Py_DEBUG),
         'safe_path': 0,
         '_is_python_build': IGNORE_CONFIG,
     }
@@ -990,33 +998,26 @@ def test_init_env_dev_mode_alloc(self):
                                api=API_COMPAT)
 
     def test_init_dev_mode(self):
-        preconfig = {
-            'allocator': PYMEM_ALLOCATOR_DEBUG,
-        }
+        preconfig = {}
         config = {
-            'faulthandler': 1,
             'dev_mode': 1,
-            'warnoptions': ['default'],
         }
+        config_dev_mode(preconfig, config)
         self.check_all_configs("test_init_dev_mode", config, preconfig,
                                api=API_PYTHON)
 
     def test_preinit_parse_argv(self):
         # Pre-initialize implicitly using argv: make sure that -X dev
         # is used to configure the allocation in preinitialization
-        preconfig = {
-            'allocator': PYMEM_ALLOCATOR_DEBUG,
-        }
+        preconfig = {}
         config = {
             'argv': ['script.py'],
             'orig_argv': ['python3', '-X', 'dev', '-P', 'script.py'],
             'run_filename': os.path.abspath('script.py'),
-            'dev_mode': 1,
-            'faulthandler': 1,
-            'warnoptions': ['default'],
             'xoptions': ['dev'],
             'safe_path': 1,
         }
+        config_dev_mode(preconfig, config)
         self.check_all_configs("test_preinit_parse_argv", config, preconfig,
                                api=API_PYTHON)
 
@@ -1615,16 +1616,15 @@ def test_init_warnoptions(self):
             'ignore:::PySys_AddWarnOption2',  # PySys_AddWarnOption()
             'ignore:::PyConfig_BeforeRead',   # PyConfig.warnoptions
             'ignore:::PyConfig_AfterRead']    # PyWideStringList_Append()
-        preconfig = dict(allocator=PYMEM_ALLOCATOR_DEBUG)
+        preconfig = {}
         config = {
-            'dev_mode': 1,
-            'faulthandler': 1,
             'bytes_warning': 1,
-            'warnoptions': warnoptions,
             'orig_argv': ['python3',
                           '-Wignore:::cmdline1',
                           '-Wignore:::cmdline2'],
         }
+        config_dev_mode(preconfig, config)
+        config['warnoptions'] = warnoptions
         self.check_all_configs("test_init_warnoptions", config, preconfig,
                                api=API_PYTHON)
 
@@ -1637,6 +1637,21 @@ def test_init_set_config(self):
         self.check_all_configs("test_init_set_config", config,
                                api=API_ISOLATED)
 
+    def test_initconfig_api(self):
+        preconfig = {}
+        config = {
+            'dev_mode': 1,
+            'pycache_prefix': 'conf_pycache_prefix',
+            'argv': ['-c'],
+            'orig_argv': ['./_testembed', '-c', 'pass'],
+            'run_command': 'pass\n',
+            'xoptions': ['faulthandler'],
+            'faulthandler': 1,
+        }
+        config_dev_mode(preconfig, config)
+        self.check_all_configs("test_initconfig_api", config, preconfig,
+                               api=API_PYTHON)
+
     def test_get_argc_argv(self):
         self.run_embedded_interpreter("test_get_argc_argv")
         # ignore output

Programs/_testembed.c

@@ -1729,6 +1729,63 @@ static int test_init_set_config(void)
 }
 
 
+static int test_initconfig_api(void)
+{
+    PyInitConfig *config = PyInitConfig_Python_New();
+    if (config == NULL) {
+        printf("Init allocation error\n");
+        return 1;
+    }
+
+    if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
+        goto error;
+    }
+
+    // Set a list of wide strings (argv)
+    wchar_t *argv[] = {PROGRAM_NAME, L"-c", L"pass"};
+    if (PyInitConfig_SetWStrList(config, "argv",
+                                 Py_ARRAY_LENGTH(argv), argv) < 0) {
+        goto error;
+    }
+
+    if (PyInitConfig_SetInt(config, "hash_seed", 10) < 0) {
+        goto error;
+    }
+
+    // Set a wide string (program_name)
+    if (PyInitConfig_SetWStr(config, "program_name", PROGRAM_NAME) < 0) {
+        goto error;
+    }
+
+    // Set a bytes string (pycache_prefix)
+    if (PyInitConfig_SetStr(config, "pycache_prefix",
+                            "conf_pycache_prefix") < 0) {
+        goto error;
+    }
+
+    // Set a list of bytes strings (xoptions)
+    char* xoptions[] = {"faulthandler"};
+    if (PyInitConfig_SetStrList(config, "xoptions",
+                                Py_ARRAY_LENGTH(xoptions), xoptions) < 0) {
+        goto error;
+    }
+
+
+    if (Py_InitializeFromInitConfig(config) < 0) {
+        Py_ExitWithInitConfig(config);
+    }
+    PyInitConfig_Free(config);
+
+    dump_config();
+    Py_Finalize();
+    return 0;
+
+error:
+    printf("Init failed:\n");
+    Py_ExitWithInitConfig(config);
+}
+
+
 static void configure_init_main(PyConfig *config)
 {
     wchar_t* argv[] = {
@@ -2131,6 +2188,7 @@ static struct TestCase TestCases[] = {
     {"test_init_is_python_build", test_init_is_python_build},
     {"test_init_warnoptions", test_init_warnoptions},
     {"test_init_set_config", test_init_set_config},
+    {"test_initconfig_api", test_initconfig_api},
     {"test_run_main", test_run_main},
     {"test_run_main_loop", test_run_main_loop},
     {"test_get_argc_argv", test_get_argc_argv},