diff --git a/peps/pep-0741.rst b/peps/pep-0741.rst index ac0b4e70b..ccf258df8 100644 --- a/peps/pep-0741.rst +++ b/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_CreateIsolated()``. + * ``PyInitConfig_Create()``. * ``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 + `_. 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 - `_. - ``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 ===========