From 441b10cf2855955c86565f8d59e72c2efc0f0a57 Mon Sep 17 00:00:00 2001
From: Victor Stinner <vstinner@python.org>
Date: Sat, 28 Sep 2019 04:28:35 +0200
Subject: 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.
---
 Doc/c-api/init_config.rst | 44 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 39 insertions(+), 5 deletions(-)

(limited to 'Doc/c-api/init_config.rst')

diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
index 0c3c725c84..58e417441d 100644
--- a/Doc/c-api/init_config.rst
+++ b/Doc/c-api/init_config.rst
@@ -194,18 +194,25 @@ PyPreConfig
    * Configure the LC_CTYPE locale
    * Set the UTF-8 mode
 
+   The :c:member:`struct_size` field must be explicitly initialized to
+   ``sizeof(PyPreConfig)``.
+
    Function to initialize a preconfiguration:
 
-   .. c:function:: void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)
+   .. c:function:: PyStatus PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)
 
       Initialize the preconfiguration with :ref:`Python Configuration
       <init-python-config>`.
 
-   .. c:function:: void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
+   .. c:function:: PyStatus PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
 
       Initialize the preconfiguration with :ref:`Isolated Configuration
       <init-isolated-conf>`.
 
+   The caller of these functions is responsible to handle exceptions (error or
+   exit) using :c:func:`PyStatus_Exception` and
+   :c:func:`Py_ExitStatusException`.
+
    Structure fields:
 
    .. c:member:: int allocator
@@ -267,6 +274,13 @@ PyPreConfig
       same way the regular Python parses command line arguments: see
       :ref:`Command Line Arguments <using-on-cmdline>`.
 
+   .. c:member:: size_t struct_size
+
+      Size of the structure in bytes: must be initialized to
+      ``sizeof(PyPreConfig)``.
+
+      Field used for API and ABI compatibility.
+
    .. c:member:: int use_environment
 
       See :c:member:`PyConfig.use_environment`.
@@ -316,12 +330,18 @@ the preinitialization.
 
 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);
     }
@@ -340,6 +360,9 @@ PyConfig
 
    Structure containing most parameters to configure Python.
 
+   The :c:member:`struct_size` field must be explicitly initialized to
+   ``sizeof(PyConfig)``.
+
    Structure methods:
 
    .. c:function:: PyStatus PyConfig_InitPythonConfig(PyConfig *config)
@@ -656,6 +679,13 @@ PyConfig
       Encoding and encoding errors of :data:`sys.stdin`, :data:`sys.stdout` and
       :data:`sys.stderr`.
 
+   .. c:member:: size_t struct_size
+
+      Size of the structure in bytes: must be initialized to
+      ``sizeof(PyConfig)``.
+
+      Field used for API and ABI compatibility.
+
    .. c:member:: int tracemalloc
 
       If non-zero, call :func:`tracemalloc.start` at startup.
@@ -718,6 +748,7 @@ Example setting the program name::
     {
         PyStatus status;
         PyConfig config;
+        config.struct_size = sizeof(PyConfig);
 
         status = PyConfig_InitPythonConfig(&config);
         if (PyStatus_Exception(status)) {
@@ -750,6 +781,7 @@ configuration, and then override some parameters::
     {
         PyStatus status;
         PyConfig config;
+        config.struct_size = sizeof(PyConfig);
 
         status = PyConfig_InitPythonConfig(&config);
         if (PyStatus_Exception(status)) {
@@ -835,8 +867,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)) {
@@ -1028,6 +1061,7 @@ phases::
     {
         PyStatus status;
         PyConfig config;
+        config.struct_size = sizeof(PyConfig);
 
         status = PyConfig_InitPythonConfig(&config);
         if (PyStatus_Exception(status)) {
-- 
cgit v1.2.1