PEP 741: Update (#3800)

* Describe relation with PEP 587 PyConfig API.
* Remove PyInitConfig_CreatePython().
* Rename PyInitConfig_CreateIsolated() to PyInitConfig_Create().
* Rejected Ideas: locale encoding and wide strings.

peps/pep-0741.rst

@@ -20,16 +20,23 @@ used to add a built-in extension module; feature previously referred to
 as the "inittab".
 
 Add ``PyConfig_Get()`` and ``PyConfig_Set()`` functions to
-get and set the current runtime configuration at runtime.
+get and set the current runtime configuration.
 
 :pep:`587` "Python Initialization Configuration" unified all the ways to
 configure the Python **initialization**. This PEP unifies also the
 configuration of the Python **preinitialization** and the Python
-**initialization** in a single API.
+**initialization** in a single API. Moreover, this PEP only provides a
+single choice to embed Python, instead of having two "Python" and
+"Isolated" choices (:pep:`587`), to simplify the API further.
 
 This new API replaces the deprecated and incomplete legacy API which is
 scheduled for removal between Python 3.13 and Python 3.15.
 
+The lower level :pep:`587` ``PyConfig`` API remains available for use
+cases with an intentionally higher level of coupling to CPython
+implementation details (such as emulating the full functionality of
+CPython's CLI, including its configuration mechanisms).
+
 
 Rationale
 =========
@@ -184,8 +191,7 @@ initialization:
 * Create config:
 
   * ``PyInitConfig`` opaque structure.
-  * ``PyInitConfig_CreatePython()``.
+  * ``PyInitConfig_Create()``.
-  * ``PyInitConfig_CreateIsolated()``.
   * ``PyInitConfig_Free(config)``.
 
 * Get options:
@@ -524,20 +530,15 @@ Create Config
     Opaque structure to configure the Python preinitialization and the
     Python initialization.
 
-``PyInitConfig* PyInitConfig_CreatePython(void)``:
+``PyInitConfig* PyInitConfig_Create(void)``:
     Create a new initialization configuration using default values
-    of the `Python Configuration
+    of the `Isolated Configuration
-    <https://docs.python.org/dev/c-api/init_config.html#python-configuration>`_.
+    <https://docs.python.org/dev/c-api/init_config.html#isolated-configuration>`_.
 
     It must be freed with ``PyInitConfig_Free()``.
 
     Return ``NULL`` on memory allocation failure.
 
-``PyInitConfig* PyInitConfig_CreateIsolated(void)``:
-    Similar to ``PyInitConfig_CreatePython()``, but use default values
-    of the `Isolated Configuration
-    <https://docs.python.org/dev/c-api/init_config.html#isolated-configuration>`_.
-
 ``void PyInitConfig_Free(PyInitConfig *config)``:
     Free memory of an initialization configuration.
 
@@ -736,6 +737,24 @@ Moreover, configuration options can be added, deprecated and removed
 following the usual :pep:`387` deprecation process.
 
 
+Interaction with the PyPreConfig and PyConfig APIs
+--------------------------------------------------
+
+The lower level :pep:`587` ``PyPreConfig`` and ``PyConfig`` APIs  remain
+available and fully supported. As noted in the Abstract, they remain the
+preferred approach for embedding use cases that are aiming to closely
+emulate the behaviour of the full CPython CLI, rather than just making a
+Python runtime available as part of a larger application.
+
+The ``PyPreConfig`` APIs may be used in combination with the
+initialization API in this PEP. In such cases, the read-only vs
+read/write restrictions for preconfiguration settings apply to
+``PyInitConfig_SetInt`` in addition to ``PyConfig_Set`` once the
+interpreter has been preconfigured (specifically, only
+``use_environment`` may be updated, attempting to update any of the
+other preconfiguration variables will report an error).
+
+
 Examples
 ========
 
@@ -749,7 +768,7 @@ return -1 on error:
 
     int init_python(void)
     {
-        PyInitConfig *config = PyInitConfig_CreatePython();
+        PyInitConfig *config = PyInitConfig_Create();
         if (config == NULL) {
             printf("PYTHON INIT ERROR: memory allocation failed\n");
             return -1;
@@ -969,6 +988,17 @@ purpose can lead to duplicate members, similar issue than duplicated
 members between existing ``PyPreConfig`` and ``PyConfig`` structures.
 
 
+Locale encoding and wide strings
+--------------------------------
+
+Accepting strings encoded to the locale encoding and accepting wide
+strings (``wchar_t*``) in the ``PyInitConfig`` API was deferred to keep
+the ``PyInitConfig`` API simple and avoid the complexity of the Python
+preinitialization. These features are also mostly needed when emulating
+the full CPython CLI behaviour, and hence better served by the lower
+level :pep:`587` API.
+
+
 Discussions
 ===========