bpo-44113: Deprecate old functions to config Python init (GH-26060)

Deprecate the following functions to configure the Python
initialization:

* PySys_AddWarnOption()
* PySys_AddWarnOptionUnicode()
* PySys_AddXOption()
* PySys_HasWarnOptions()
* Py_SetPath()
* Py_SetProgramName()
* Py_SetPythonHome()
* Py_SetStandardStreamEncoding()
* _Py_SetProgramFullPath()

Use the new PyConfig API of the Python Initialization Configuration
instead (PEP 587).

Author: vstinner

Doc/c-api/init.rst

@@ -323,6 +323,11 @@ Process-wide parameters
       single: main()
       triple: stdin; stdout; sdterr
 
+   This API is kept for backward compatibility: setting
+   :c:member:`PyConfig.stdio_encoding` and :c:member:`PyConfig.stdio_errors`
+   should be used instead, see :ref:`Python Initialization Configuration
+   <init-config>`.
+
    This function should be called before :c:func:`Py_Initialize`, if it is
    called at all. It specifies which encoding and error handling to use
    with standard IO, with the same meanings as in :func:`str.encode`.
@@ -345,6 +350,8 @@ Process-wide parameters
 
    .. versionadded:: 3.4
 
+   .. deprecated:: 3.11
+
 
 .. c:function:: void Py_SetProgramName(const wchar_t *name)
 
@@ -353,6 +360,10 @@ Process-wide parameters
       single: main()
       single: Py_GetPath()
 
+   This API is kept for backward compatibility: setting
+   :c:member:`PyConfig.program_name` should be used instead, see :ref:`Python
+   Initialization Configuration <init-config>`.
+
    This function should be called before :c:func:`Py_Initialize` is called for
    the first time, if it is called at all.  It tells the interpreter the value
    of the ``argv[0]`` argument to the :c:func:`main` function of the program
@@ -367,6 +378,8 @@ Process-wide parameters
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:type:`wchar_*` string.
 
+   .. deprecated:: 3.11
+
 
 .. c:function:: wchar* Py_GetProgramName()
 
@@ -495,6 +508,11 @@ Process-wide parameters
       single: path (in module sys)
       single: Py_GetPath()
 
+   This API is kept for backward compatibility: setting
+   :c:member:`PyConfig.module_search_paths` and
+   :c:member:`PyConfig.module_search_paths_set` should be used instead, see
+   :ref:`Python Initialization Configuration <init-config>`.
+
    Set the default module search path.  If this function is called before
    :c:func:`Py_Initialize`, then :c:func:`Py_GetPath` won't attempt to compute a
    default search path but uses the one provided instead.  This is useful if
@@ -518,6 +536,8 @@ Process-wide parameters
       The program full path is now used for :data:`sys.executable`, instead
       of the program name.
 
+   .. deprecated:: 3.11
+
 
 .. c:function:: const char* Py_GetVersion()
 
@@ -617,6 +637,9 @@ Process-wide parameters
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:type:`wchar_*` string.
 
+   See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
+   members of the :ref:`Python Initialization Configuration <init-config>`.
+
    .. note::
       It is recommended that applications embedding the Python interpreter
       for purposes other than executing a single script pass ``0`` as *updatepath*,
@@ -644,11 +667,18 @@ Process-wide parameters
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:type:`wchar_*` string.
 
+   See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
+   members of the :ref:`Python Initialization Configuration <init-config>`.
+
    .. versionchanged:: 3.4 The *updatepath* value depends on :option:`-I`.
 
 
 .. c:function:: void Py_SetPythonHome(const wchar_t *home)
 
+   This API is kept for backward compatibility: setting
+   :c:member:`PyConfig.home` should be used instead, see :ref:`Python
+   Initialization Configuration <init-config>`.
+
    Set the default "home" directory, that is, the location of the standard
    Python libraries.  See :envvar:`PYTHONHOME` for the meaning of the
    argument string.
@@ -661,6 +691,8 @@ Process-wide parameters
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:type:`wchar_*` string.
 
+   .. deprecated:: 3.11
+
 
 .. c:function:: w_char* Py_GetPythonHome()
 

Doc/c-api/memory.rst

@@ -476,6 +476,8 @@ Customize Memory Allocators
    the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the
    debug hooks on top on the new allocator.
 
+   See also :c:member:`PyPreConfig.allocator` and :ref:`Preinitialize Python
+   with PyPreConfig <c-preinit>`.
 
 .. c:function:: void PyMem_SetupDebugHooks(void)
 

Doc/c-api/sys.rst

@@ -237,11 +237,21 @@ accessible to C code.  They all work with the current interpreter thread's
 
 .. c:function:: void PySys_AddWarnOption(const wchar_t *s)
 
+   This API is kept for backward compatibility: setting
+   :c:member:`PyConfig.warnoptions` should be used instead, see :ref:`Python
+   Initialization Configuration <init-config>`.
+
    Append *s* to :data:`sys.warnoptions`. This function must be called prior
    to :c:func:`Py_Initialize` in order to affect the warnings filter list.
 
+   .. deprecated:: 3.11
+
 .. c:function:: void PySys_AddWarnOptionUnicode(PyObject *unicode)
 
+   This API is kept for backward compatibility: setting
+   :c:member:`PyConfig.warnoptions` should be used instead, see :ref:`Python
+   Initialization Configuration <init-config>`.
+
    Append *unicode* to :data:`sys.warnoptions`.
 
    Note: this function is not currently usable from outside the CPython
@@ -250,6 +260,8 @@ accessible to C code.  They all work with the current interpreter thread's
    called until enough of the runtime has been initialized to permit the
    creation of Unicode objects.
 
+   .. deprecated:: 3.11
+
 .. c:function:: void PySys_SetPath(const wchar_t *path)
 
    Set :data:`sys.path` to a list object of paths found in *path* which should
@@ -294,12 +306,18 @@ accessible to C code.  They all work with the current interpreter thread's
 
 .. c:function:: void PySys_AddXOption(const wchar_t *s)
 
+   This API is kept for backward compatibility: setting
+   :c:member:`PyConfig.xoptions` should be used instead, see :ref:`Python
+   Initialization Configuration <init-config>`.
+
    Parse *s* as a set of :option:`-X` options and add them to the current
    options mapping as returned by :c:func:`PySys_GetXOptions`. This function
    may be called prior to :c:func:`Py_Initialize`.
 
    .. versionadded:: 3.2
 
+   .. deprecated:: 3.11
+
 .. c:function:: PyObject *PySys_GetXOptions()
 
    Return the current dictionary of :option:`-X` options, similarly to

Doc/whatsnew/3.11.rst

@@ -139,3 +139,19 @@ Removed
 * :c:func:`PyFrame_BlockSetup` and :c:func:`PyFrame_BlockPop` have been
   removed.
   (Contributed by Mark Shannon in :issue:`40222`.)
+
+* Deprecate the following functions to configure the Python initialization:
+
+  * :c:func:`PySys_AddWarnOptionUnicode`
+  * :c:func:`PySys_AddWarnOption`
+  * :c:func:`PySys_AddXOption`
+  * :c:func:`PySys_HasWarnOptions`
+  * :c:func:`Py_SetPath`
+  * :c:func:`Py_SetProgramName`
+  * :c:func:`Py_SetPythonHome`
+  * :c:func:`Py_SetStandardStreamEncoding`
+  * :c:func:`_Py_SetProgramFullPath`
+
+  Use the new :c:type:`PyConfig` API of the :ref:`Python Initialization Configuration
+  <init-config>` instead (:pep:`587`).
+  (Contributed by Victor Stinner in :issue:`44113`.)

Include/cpython/pylifecycle.h

@@ -5,8 +5,9 @@
 /* Only used by applications that embed the interpreter and need to
  * override the standard encoding determination mechanism
  */
-PyAPI_FUNC(int) Py_SetStandardStreamEncoding(const char *encoding,
-                                             const char *errors);
+Py_DEPRECATED(3.11) PyAPI_FUNC(int) Py_SetStandardStreamEncoding(
+    const char *encoding,
+    const char *errors);
 
 /* PEP 432 Multi-phase initialization API (Private while provisional!) */
 
@@ -41,7 +42,7 @@ PyAPI_FUNC(void) _Py_RestoreSignals(void);
 PyAPI_FUNC(int) Py_FdIsInteractive(FILE *, const char *);
 PyAPI_FUNC(int) _Py_FdIsInteractive(FILE *fp, PyObject *filename);
 
-PyAPI_FUNC(void) _Py_SetProgramFullPath(const wchar_t *);
+Py_DEPRECATED(3.11) PyAPI_FUNC(void) _Py_SetProgramFullPath(const wchar_t *);
 
 PyAPI_FUNC(const char *) _Py_gitidentifier(void);
 PyAPI_FUNC(const char *) _Py_gitversion(void);

Include/pylifecycle.h

@@ -37,18 +37,18 @@ PyAPI_FUNC(int) Py_FrozenMain(int argc, char **argv);
 PyAPI_FUNC(int) Py_BytesMain(int argc, char **argv);
 
 /* In pathconfig.c */
-PyAPI_FUNC(void) Py_SetProgramName(const wchar_t *);
+Py_DEPRECATED(3.11) PyAPI_FUNC(void) Py_SetProgramName(const wchar_t *);
 PyAPI_FUNC(wchar_t *) Py_GetProgramName(void);
 
-PyAPI_FUNC(void) Py_SetPythonHome(const wchar_t *);
+Py_DEPRECATED(3.11) PyAPI_FUNC(void) Py_SetPythonHome(const wchar_t *);
 PyAPI_FUNC(wchar_t *) Py_GetPythonHome(void);
 
 PyAPI_FUNC(wchar_t *) Py_GetProgramFullPath(void);
 
 PyAPI_FUNC(wchar_t *) Py_GetPrefix(void);
 PyAPI_FUNC(wchar_t *) Py_GetExecPrefix(void);
 PyAPI_FUNC(wchar_t *) Py_GetPath(void);
-PyAPI_FUNC(void)      Py_SetPath(const wchar_t *);
+Py_DEPRECATED(3.11) PyAPI_FUNC(void) Py_SetPath(const wchar_t *);
 #ifdef MS_WINDOWS
 int _Py_CheckPython3(void);
 #endif

Include/sysmodule.h

@@ -22,11 +22,11 @@ PyAPI_FUNC(void) PySys_FormatStdout(const char *format, ...);
 PyAPI_FUNC(void) PySys_FormatStderr(const char *format, ...);
 
 PyAPI_FUNC(void) PySys_ResetWarnOptions(void);
-PyAPI_FUNC(void) PySys_AddWarnOption(const wchar_t *);
-PyAPI_FUNC(void) PySys_AddWarnOptionUnicode(PyObject *);
-PyAPI_FUNC(int) PySys_HasWarnOptions(void);
+Py_DEPRECATED(3.11) PyAPI_FUNC(void) PySys_AddWarnOption(const wchar_t *);
+Py_DEPRECATED(3.11) PyAPI_FUNC(void) PySys_AddWarnOptionUnicode(PyObject *);
+Py_DEPRECATED(3.11) PyAPI_FUNC(int) PySys_HasWarnOptions(void);
 
-PyAPI_FUNC(void) PySys_AddXOption(const wchar_t *);
+Py_DEPRECATED(3.11) PyAPI_FUNC(void) PySys_AddXOption(const wchar_t *);
 PyAPI_FUNC(PyObject *) PySys_GetXOptions(void);
 
 #ifndef Py_LIMITED_API

Misc/NEWS.d/next/C API/2021-05-12-12-24-45.bpo-44113.DcgOqE.rst

@@ -0,0 +1,14 @@
+Deprecate the following functions to configure the Python initialization:
+
+* :c:func:`PySys_AddWarnOptionUnicode`
+* :c:func:`PySys_AddWarnOption`
+* :c:func:`PySys_AddXOption`
+* :c:func:`PySys_HasWarnOptions`
+* :c:func:`Py_SetPath`
+* :c:func:`Py_SetProgramName`
+* :c:func:`Py_SetPythonHome`
+* :c:func:`Py_SetStandardStreamEncoding`
+* :c:func:`_Py_SetProgramFullPath`
+
+Use the new :c:type:`PyConfig` API of the :ref:`Python Initialization
+Configuration <init-config>` instead (:pep:`587`).

Programs/_testembed.c

@@ -22,6 +22,11 @@
 /* Use path starting with "./" avoids a search along the PATH */
 #define PROGRAM_NAME L"./_testembed"
 
+// Ignore Py_DEPRECATED() compiler warnings: deprecated functions are
+// tested on purpose here.
+_Py_COMP_DIAG_PUSH
+_Py_COMP_DIAG_IGNORE_DEPR_DECLS
+
 static void _testembed_Py_Initialize(void)
 {
     Py_SetProgramName(PROGRAM_NAME);