bpo-38304: Add PyConfig.struct_size (GH-16451)

Add a new struct_size field to PyPreConfig and PyConfig structures to
allow to modify these structures in the future without breaking the
backward compatibility.

* Replace private _config_version field with public struct_size field
  in PyPreConfig and PyConfig.
* Public PyPreConfig_InitIsolatedConfig() and
  PyPreConfig_InitPythonConfig()
  return type becomes PyStatus, instead of void.
* Internal _PyConfig_InitCompatConfig(),
  _PyPreConfig_InitCompatConfig(), _PyPreConfig_InitFromConfig(),
  _PyPreConfig_InitFromPreConfig() return type becomes PyStatus,
  instead of void.
* Remove _Py_CONFIG_VERSION
* Update the Initialization Configuration documentation.

2 files changed, 16 insertions, 13 deletions

diff --git a/Include/cpython/initconfig.h b/Include/cpython/initconfig.h
index 047f511..d5effb8 100644
--- a/Include/cpython/initconfig.h
+++ b/Include/cpython/initconfig.h
@@ -45,8 +45,10 @@ PyAPI_FUNC(PyStatus) PyWideStringList_Insert(PyWideStringList *list,
 /* --- PyPreConfig ----------------------------------------------- */
 
 typedef struct {
-    int _config_version;  /* Internal configuration version,
-                             used for ABI compatibility */
+    /* Size of the structure in bytes: must be initialized to
+       sizeof(PyPreConfig). Field used for API and ABI compatibility. */
+    size_t struct_size;
+
     int _config_init;     /* _PyConfigInitEnum value */
 
     /* Parse Py_PreInitializeFromBytesArgs() arguments?
@@ -122,15 +124,17 @@ typedef struct {
     int allocator;
 } PyPreConfig;
 
-PyAPI_FUNC(void) PyPreConfig_InitPythonConfig(PyPreConfig *config);
-PyAPI_FUNC(void) PyPreConfig_InitIsolatedConfig(PyPreConfig *config);
+PyAPI_FUNC(PyStatus) PyPreConfig_InitPythonConfig(PyPreConfig *config);
+PyAPI_FUNC(PyStatus) PyPreConfig_InitIsolatedConfig(PyPreConfig *config);
 
 
 /* --- PyConfig ---------------------------------------------- */
 
 typedef struct {
-    int _config_version;  /* Internal configuration version,
-                             used for ABI compatibility */
+    /* Size of the structure in bytes: must be initialized to
+       sizeof(PyConfig). Field used for API and ABI compatibility. */
+    size_t struct_size;
+
     int _config_init;     /* _PyConfigInitEnum value */
 
     int isolated;         /* Isolated mode? see PyPreConfig.isolated */
@@ -403,7 +407,6 @@ typedef struct {
 
     /* If equal to 0, stop Python initialization before the "main" phase */
     int _init_main;
-
 } PyConfig;
 
 PyAPI_FUNC(PyStatus) PyConfig_InitPythonConfig(PyConfig *config);
diff --git a/Include/internal/pycore_initconfig.h b/Include/internal/pycore_initconfig.h
index a7c1994..dcdb616 100644
--- a/Include/internal/pycore_initconfig.h
+++ b/Include/internal/pycore_initconfig.h
@@ -40,6 +40,8 @@ extern "C" {
     (err._type == _PyStatus_TYPE_EXIT)
 #define _PyStatus_EXCEPTION(err) \
     (err._type != _PyStatus_TYPE_OK)
+#define _PyStatus_UPDATE_FUNC(err) \
+    do { err.func = _PyStatus_GET_FUNC(); } while (0)
 
 /* --- PyWideStringList ------------------------------------------------ */
 
@@ -118,11 +120,11 @@ extern PyStatus _PyPreCmdline_Read(_PyPreCmdline *cmdline,
 
 /* --- PyPreConfig ----------------------------------------------- */
 
-PyAPI_FUNC(void) _PyPreConfig_InitCompatConfig(PyPreConfig *preconfig);
-extern void _PyPreConfig_InitFromConfig(
+PyAPI_FUNC(PyStatus) _PyPreConfig_InitCompatConfig(PyPreConfig *preconfig);
+extern PyStatus _PyPreConfig_InitFromConfig(
     PyPreConfig *preconfig,
     const PyConfig *config);
-extern void _PyPreConfig_InitFromPreConfig(
+extern PyStatus _PyPreConfig_InitFromPreConfig(
     PyPreConfig *preconfig,
     const PyPreConfig *config2);
 extern PyObject* _PyPreConfig_AsDict(const PyPreConfig *preconfig);
@@ -135,8 +137,6 @@ extern PyStatus _PyPreConfig_Write(const PyPreConfig *preconfig);
 
 /* --- PyConfig ---------------------------------------------- */
 
-#define _Py_CONFIG_VERSION 1
-
 typedef enum {
     /* Py_Initialize() API: backward compatibility with Python 3.6 and 3.7 */
     _PyConfig_INIT_COMPAT = 1,
@@ -144,7 +144,7 @@ typedef enum {
     _PyConfig_INIT_ISOLATED = 3
 } _PyConfigInitEnum;
 
-PyAPI_FUNC(void) _PyConfig_InitCompatConfig(PyConfig *config);
+PyAPI_FUNC(PyStatus) _PyConfig_InitCompatConfig(PyConfig *config);
 extern PyStatus _PyConfig_Copy(
     PyConfig *config,
     const PyConfig *config2);