gh-158001: Remove Py_SetProgramName() function (#158024)

Remove Py_SetProgramName(), Py_SetPythonHome(), PySys_SetArgv() and
PySys_SetArgvEx() functions, deprecated since Python 3.11.

Mark the 4 functions as abi_only in stable_abi.toml.

Author: vstinner

Doc/c-api/interp-lifecycle.rst

@@ -37,8 +37,6 @@ The following functions can be safely called before Python is initialized:
   * :c:func:`PyMem_SetAllocator`
   * :c:func:`PyMem_SetupDebugHooks`
   * :c:func:`PyObject_SetArenaAllocator`
-  * :c:func:`Py_SetProgramName`
-  * :c:func:`Py_SetPythonHome`
   * the configuration functions covered in :ref:`init-config`
 
 * Informative functions:
@@ -778,33 +776,6 @@ deleted. This can be done using interpreter views.
 Process-wide parameters
 -----------------------
 
-.. c:function:: void Py_SetProgramName(const wchar_t *name)
-
-   .. index::
-      single: Py_Initialize()
-      single: main()
-
-   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
-   (converted to wide characters).
-   This is used by some other functions below to find
-   the Python run-time libraries relative to the interpreter executable.  The
-   default value is ``'python'``.  The argument should point to a
-   zero-terminated wide character string in static storage whose contents will not
-   change for the duration of the program's execution.  No code in the Python
-   interpreter will change the contents of this storage.
-
-   Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
-   :c:expr:`wchar_t*` string.
-
-   .. deprecated-removed:: 3.11 3.16
-
-
 .. c:function:: const char* Py_GetVersion()
 
    Return the version of this Python interpreter.  This is a string that looks
@@ -873,100 +844,3 @@ Process-wide parameters
    The returned string points into static storage; the caller should not modify its
    value.  The value is available to Python code as part of the variable
    ``sys.version``.
-
-
-.. c:function:: void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
-
-   .. index::
-      single: main()
-      single: Py_FatalError()
-      single: argv (in module sys)
-
-   This API is kept for backward compatibility: setting
-   :c:member:`PyConfig.argv`, :c:member:`PyConfig.parse_argv` and
-   :c:member:`PyConfig.safe_path` should be used instead, see :ref:`Python
-   Initialization Configuration <init-config>`.
-
-   Set :data:`sys.argv` based on *argc* and *argv*.  These parameters are
-   similar to those passed to the program's :c:func:`main` function with the
-   difference that the first entry should refer to the script file to be
-   executed rather than the executable hosting the Python interpreter.  If there
-   isn't a script that will be run, the first entry in *argv* can be an empty
-   string.  If this function fails to initialize :data:`sys.argv`, a fatal
-   condition is signalled using :c:func:`Py_FatalError`.
-
-   If *updatepath* is zero, this is all the function does.  If *updatepath*
-   is non-zero, the function also modifies :data:`sys.path` according to the
-   following algorithm:
-
-   - If the name of an existing script is passed in ``argv[0]``, the absolute
-     path of the directory where the script is located is prepended to
-     :data:`sys.path`.
-   - Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point
-     to an existing file name), an empty string is prepended to
-     :data:`sys.path`, which is the same as prepending the current working
-     directory (``"."``).
-
-   Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
-   :c:expr:`wchar_t*` 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*,
-      and update :data:`sys.path` themselves if desired.
-      See :cve:`2008-5983`.
-
-      On versions before 3.1.3, you can achieve the same effect by manually
-      popping the first :data:`sys.path` element after having called
-      :c:func:`PySys_SetArgv`, for example using::
-
-         PyRun_SimpleString("import sys; sys.path.pop(0)\n");
-
-   .. versionadded:: 3.1.3
-
-   .. deprecated-removed:: 3.11 3.16
-
-
-.. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
-
-   This API is kept for backward compatibility: setting
-   :c:member:`PyConfig.argv` and :c:member:`PyConfig.parse_argv` should be used
-   instead, see :ref:`Python Initialization Configuration <init-config>`.
-
-   This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set
-   to ``1`` unless the :program:`python` interpreter was started with the
-   :option:`-I`.
-
-   Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
-   :c:expr:`wchar_t*` 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`.
-
-   .. deprecated-removed:: 3.11 3.16
-
-
-.. 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.
-
-   The argument should point to a zero-terminated character string in static
-   storage whose contents will not change for the duration of the program's
-   execution.  No code in the Python interpreter will change the contents of
-   this storage.
-
-   Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
-   :c:expr:`wchar_t*` string.
-
-   .. deprecated-removed:: 3.11 3.16

Doc/data/refcounts.dat

@@ -2265,15 +2265,6 @@ PySys_GetObject:const char*:name::
 
 PySys_GetXOptions:PyObject*::0:
 
-PySys_SetArgv:void:::
-PySys_SetArgv:int:argc::
-PySys_SetArgv:wchar_t**:argv::
-
-PySys_SetArgvEx:void:::
-PySys_SetArgvEx:int:argc::
-PySys_SetArgvEx:wchar_t**:argv::
-PySys_SetArgvEx:int:updatepath::
-
 PySys_SetObject:int:::
 PySys_SetObject:const char*:name::
 PySys_SetObject:PyObject*:v:+1:
@@ -3085,9 +3076,6 @@ Py_ReprEnter:PyObject*:object:+1:
 Py_ReprLeave:void:::
 Py_ReprLeave:PyObject*:object:-1:
 
-Py_SetProgramName:void:::
-Py_SetProgramName:const wchar_t*:name::
-
 Py_XDECREF:void:::
 Py_XDECREF:PyObject*:o:-1:if o is not NULL
 

Doc/data/stable_abi.dat

@@ -3,6 +3,10 @@
 # Remove from here in 3.16
 c-api/allocation.html: deprecated-aliases
 c-api/file.html: deprecated-api
+c-api/interp-lifecycle.html: c.PySys_SetArgv
+c-api/interp-lifecycle.html: c.PySys_SetArgvEx
+c-api/interp-lifecycle.html: c.Py_SetProgramName
+c-api/interp-lifecycle.html: c.Py_SetPythonHome
 c-api/threads.html: c.PyEval_InitThreads
 
 # Removed sections

Doc/tools/removed-ids.txt

@@ -1145,6 +1145,17 @@ Removed C APIs
   3.7 and was deprecated since Python 3.9.
   (Contributed by Victor Stinner in :gh:`154757`.)
 
+* Remove :c:func:`!Py_SetProgramName` and :c:func:`!Py_SetPythonHome`
+  functions, deprecated since Python 3.11. Instead, use :ref:`PyInitConfig C
+  API <pyinitconfig_api>` to set respectively ``"program_name"`` and
+  ``"home"``.
+  (Contributed by Victor Stinner in :gh:`158001`.)
+
+* Remove :c:func:`!PySys_SetArgv` and :c:func:`!PySys_SetArgvEx` functions,
+  deprecated since Python 3.11. Instead, set directly :data:`sys.argv`, and
+  maybe also :data:`sys.path`.
+  (Contributed by Victor Stinner in :gh:`158001`.)
+
 * The :c:var:`!PyUnstable_ExecutableKinds` array, as well as the macros
   :c:macro:`!PyUnstable_EXECUTABLE_KIND_SKIP`,
   :c:macro:`!PyUnstable_EXECUTABLE_KIND_PY_FUNCTION`,

Doc/whatsnew/3.16.rst

@@ -33,10 +33,6 @@ PyAPI_FUNC(void) _Py_NO_RETURN Py_Exit(int);
 PyAPI_FUNC(int) Py_Main(int argc, wchar_t **argv);
 PyAPI_FUNC(int) Py_BytesMain(int argc, char **argv);
 
-/* In pathconfig.c */
-Py_DEPRECATED(3.11) PyAPI_FUNC(void) Py_SetProgramName(const wchar_t *);
-Py_DEPRECATED(3.11) PyAPI_FUNC(void) Py_SetPythonHome(const wchar_t *);
-
 #ifdef MS_WINDOWS
 int _Py_CheckPython3(void);
 #endif

Include/pylifecycle.h

@@ -13,9 +13,6 @@ PyAPI_FUNC(int) PySys_GetOptionalAttrString(const char *, PyObject **);
 PyAPI_FUNC(PyObject *) PySys_GetObject(const char *);
 PyAPI_FUNC(int) PySys_SetObject(const char *, PyObject *);
 
-Py_DEPRECATED(3.11) PyAPI_FUNC(void) PySys_SetArgv(int, wchar_t **);
-Py_DEPRECATED(3.11) PyAPI_FUNC(void) PySys_SetArgvEx(int, wchar_t **, int);
-
 PyAPI_FUNC(void) PySys_WriteStdout(const char *format, ...)
                  Py_GCC_ATTRIBUTE((format(printf, 1, 2)));
 PyAPI_FUNC(void) PySys_WriteStderr(const char *format, ...)

Include/sysmodule.h

@@ -0,0 +1,3 @@
+Remove :c:func:`!Py_SetProgramName`, :c:func:`!Py_SetPythonHome`,
+:c:func:`!PySys_SetArgv` and :c:func:`!PySys_SetArgvEx` functions, deprecated
+since Python 3.11. Patch by Victor Stinner.

Misc/NEWS.d/next/C_API/2026-09-23-21-45-43.gh-issue-158001.R_wX4E.rst

@@ -1350,8 +1350,10 @@
     abi_only = true
 [function.PySys_SetArgv]
     added = '3.2'
+    abi_only = true
 [function.PySys_SetArgvEx]
     added = '3.2'
+    abi_only = true
 [function.PySys_SetObject]
     added = '3.2'
 [function.PySys_SetPath]
@@ -1695,8 +1697,10 @@
     added = '3.2'
 [function.Py_SetProgramName]
     added = '3.2'
+    abi_only = true
 [function.Py_SetPythonHome]
     added = '3.2'
+    abi_only = true
 [function.Py_SetRecursionLimit]
     added = '3.2'
 [function.Py_VaBuildValue]

Misc/stable_abi.toml

@@ -23,6 +23,10 @@ extern void PySys_AddWarnOption(const wchar_t *s);
 extern void PySys_AddXOption(const wchar_t *s);
 extern void Py_SetPath(const wchar_t *path);
 
+// Functions removed from Python 3.16 API but still exported for the stable
+// ABI.
+extern void Py_SetPythonHome(const wchar_t *);
+
 // These functions were removed from Python 3.15 API but are still exported
 // for the stable ABI. We want to test them in this program.
 extern void PySys_ResetWarnOptions(void);