gh-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)

Add these 11 functions to the limited C API.

Changes:

* Add Include/initconfig.h header.

Author: vstinner

Doc/data/stable_abi.dat

@@ -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/Python.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 ----------------------------------------------- */
@@ -255,9 +252,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/cpython/initconfig.h

@@ -0,0 +1,96 @@
+#ifndef Py_INITCONFIG_H
+#define Py_INITCONFIG_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
+
+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);
+
+#endif  // !Py_LIMITED_API
+
+
+#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/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 ---------------------------------------------------- */

Include/internal/pycore_initconfig.h

@@ -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')
@@ -511,7 +519,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,
     }
@@ -991,33 +999,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)
 
@@ -1618,16 +1619,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)
 
@@ -1640,6 +1640,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

Lib/test/test_embed.py

@@ -2460,3 +2460,26 @@
     added = '3.13'
 [function.PyMapping_HasKeyStringWithError]
     added = '3.13'
+
+[function.PyInitConfig_Python_New]
+    added = '3.13'
+[function.PyInitConfig_Isolated_New]
+    added = '3.13'
+[function.PyInitConfig_Free]
+    added = '3.13'
+[function.PyInitConfig_SetInt]
+    added = '3.13'
+[function.PyInitConfig_SetStr]
+    added = '3.13'
+[function.PyInitConfig_SetStrList]
+    added = '3.13'
+[function.PyInitConfig_SetWStr]
+    added = '3.13'
+[function.PyInitConfig_SetWStrList]
+    added = '3.13'
+[function.PyInitConfig_GetErrorMsg]
+    added = '3.13'
+[function.Py_InitializeFromInitConfig]
+    added = '3.13'
+[function.Py_ExitWithInitConfig]
+    added = '3.13'