PEP 587: add PyConfig.struct_size

vstinner · vstinner · commit afa38c0bef77 · 2019-09-28T04:17:01.000+02:00
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.

Remove _config_version fields, replaced by struct_size.
diff --git a/pep-0587.rst b/pep-0587.rst
@@ -239,14 +239,23 @@ The ``PyPreConfig`` structure is used to preinitialize Python:
 * Configure the LC_CTYPE locale
 * Set the UTF-8 mode
 
+The ``struct_size`` field must be explicitly initialized to
+``sizeof(PyPreConfig)``.
+
 Example using the preinitialization to enable the UTF-8 Mode::
 
+    PyStatus status;
     PyPreConfig preconfig;
-    PyPreConfig_InitPythonConfig(&preconfig);
+    preconfig.struct_size = sizeof(PyPreConfig);
+
+    status = PyPreConfig_InitPythonConfig(&preconfig);
+    if (PyStatus_Exception(status)) {
+        Py_ExitStatusException(status);
+    }
 
     preconfig.utf8_mode = 1;
 
-    PyStatus status = Py_PreInitialize(&preconfig);
+    status = Py_PreInitialize(&preconfig);
     if (PyStatus_Exception(status)) {
         Py_ExitStatusException(status);
     }
@@ -259,8 +268,8 @@ Example using the preinitialization to enable the UTF-8 Mode::
 
 Function to initialize a preconfiguration:
 
-* ``void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)``
-* ``void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)``
+* ``PyStatus PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)``
+* ``PyStatus PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)``
 
 Functions to preinitialize Python:
 
@@ -318,6 +327,9 @@ an effect on the pre-configuration like encodings. For example, the
   ``Py_PreInitializeFromBytesArgs()`` parse their ``argv`` argument the
   same way the regular Python parses command line arguments: see
   `Command Line Arguments`_.
+* ``struct_size`` (``size_t``:
+  Size of the structure in bytes: must be initialized to
+  ``sizeof(PyPreConfig)``. Field used for API and ABI compatibility.
 * ``use_environment`` (``int``):
   See ``PyConfig.use_environment``.
 * ``utf8_mode`` (``int``):
@@ -328,8 +340,6 @@ The ``legacy_windows_fs_encoding`` field is only available on Windows.
 
 ``PyPreConfig`` private fields, for internal use only:
 
-* ``_config_version`` (``int``):
-  Configuration version, used for ABI compatibility.
 * ``_config_init`` (``int``):
   Function used to initialize ``PyConfig``, used for preinitialization.
 
@@ -349,12 +359,16 @@ Initialization with PyConfig
 
 The ``PyConfig`` structure contains most parameters to configure Python.
 
+The ``struct_size`` field must be explicitly initialized to
+``sizeof(PyConfig)``.
+
 Example setting the program name::
 
     void init_python(void)
     {
         PyStatus status;
         PyConfig config;
+        config.struct_size = sizeof(PyConfig);
 
         status = PyConfig_InitPythonConfig(&config);
         if (PyStatus_Exception(status)) {
@@ -557,6 +571,9 @@ exceptions (error or exit) using ``PyStatus_Exception()`` and
   ``stdio_errors`` (``wchar_t*``):
   Encoding and encoding errors of ``sys.stdin``, ``sys.stdout``
   and ``sys.stderr``.
+* ``struct_size`` (``size_t``:
+  Size of the structure in bytes: must be initialized to
+  ``sizeof(PyConfig)``. Field used for API and ABI compatibility.
 * ``tracemalloc`` (``int``):
   If non-zero, call ``tracemalloc.start(value)``.
 * ``user_site_directory`` (``int``):
@@ -582,8 +599,6 @@ Options`_.
 
 ``PyConfig`` private fields, for internal use only:
 
-* ``_config_version`` (``int``):
-  Configuration version, used for ABI compatibility.
 * ``_config_init`` (``int``):
   Function used to initialize ``PyConfig``, used for preinitialization.
 * ``_install_importlib`` (``int``):
@@ -599,6 +614,7 @@ configuration, and then override some parameters::
     {
         PyStatus status;
         PyConfig config;
+        config.struct_size = sizeof(PyConfig);
 
         status = PyConfig_InitPythonConfig(&config);
         if (PyStatus_Exception(status)) {
@@ -685,8 +701,9 @@ Example of customized Python always running in isolated mode::
 
     int main(int argc, char **argv)
     {
-        PyConfig config;
         PyStatus status;
+        PyConfig config;
+        config.struct_size = sizeof(PyConfig);
 
         status = PyConfig_InitPythonConfig(&config);
         if (PyStatus_Exception(status)) {
@@ -862,6 +879,7 @@ phases::
     {
         PyStatus status;
         PyConfig config;
+        config.struct_size = sizeof(PyConfig);
 
         status = PyConfig_InitPythonConfig(&config);
         if (PyStatus_Exception(status)) {
