bpo-38304: Add PyConfig.struct_size (GH-16451) (GH-16453)
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.
(cherry picked from commit 441b10cf2855955c86565f8d59e72c2efc0f0a57)
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
index 0c3c725..58e4174 100644
--- a/Doc/c-api/init_config.rst
+++ b/Doc/c-api/init_config.rst
@@ -194,18 +194,25 @@
* 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 @@
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 @@
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 @@
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 @@
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 @@
{
PyStatus status;
PyConfig config;
+ config.struct_size = sizeof(PyConfig);
status = PyConfig_InitPythonConfig(&config);
if (PyStatus_Exception(status)) {
@@ -750,6 +781,7 @@
{
PyStatus status;
PyConfig config;
+ config.struct_size = sizeof(PyConfig);
status = PyConfig_InitPythonConfig(&config);
if (PyStatus_Exception(status)) {
@@ -835,8 +867,9 @@
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 @@
{
PyStatus status;
PyConfig config;
+ config.struct_size = sizeof(PyConfig);
status = PyConfig_InitPythonConfig(&config);
if (PyStatus_Exception(status)) {