From 6cd0446ef72c6676b292d7f54b1ddb8ae5e1fb8d Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 12 May 2021 23:59:25 +0200 Subject: [PATCH] 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). --- Doc/c-api/init.rst | 32 +++++++++++++++++++ Doc/c-api/memory.rst | 2 ++ Doc/c-api/sys.rst | 18 +++++++++++ Doc/whatsnew/3.11.rst | 16 ++++++++++ Include/cpython/pylifecycle.h | 7 ++-- Include/pylifecycle.h | 6 ++-- Include/sysmodule.h | 8 ++--- .../2021-05-12-12-24-45.bpo-44113.DcgOqE.rst | 14 ++++++++ Programs/_testembed.c | 5 +++ 9 files changed, 98 insertions(+), 10 deletions(-) create mode 100644 Misc/NEWS.d/next/C API/2021-05-12-12-24-45.bpo-44113.DcgOqE.rst diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 0f759732b35..60564241bfd 100644 --- a/Doc/c-api/init.rst +++ b/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 + `. + 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 `. + 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 `. + 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 `. + .. 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 `. + .. 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 `. + 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() diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index efddc6f7be5..3cc9dff2d4c 100644 --- a/Doc/c-api/memory.rst +++ b/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:function:: void PyMem_SetupDebugHooks(void) diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 97717f5fc19..cca8b7bb6d6 100644 --- a/Doc/c-api/sys.rst +++ b/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 `. + 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 `. + 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 `. + 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 diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 2cca9921bf0..50368829407 100644 --- a/Doc/whatsnew/3.11.rst +++ b/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 + ` instead (:pep:`587`). + (Contributed by Victor Stinner in :issue:`44113`.) diff --git a/Include/cpython/pylifecycle.h b/Include/cpython/pylifecycle.h index 13f7a26ba12..6fe46a54401 100644 --- a/Include/cpython/pylifecycle.h +++ b/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); diff --git a/Include/pylifecycle.h b/Include/pylifecycle.h index 783fcb455eb..7925eafc660 100644 --- a/Include/pylifecycle.h +++ b/Include/pylifecycle.h @@ -37,10 +37,10 @@ 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); @@ -48,7 +48,7 @@ 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 diff --git a/Include/sysmodule.h b/Include/sysmodule.h index 670e5d283f7..8c8f7c42594 100644 --- a/Include/sysmodule.h +++ b/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 diff --git a/Misc/NEWS.d/next/C API/2021-05-12-12-24-45.bpo-44113.DcgOqE.rst b/Misc/NEWS.d/next/C API/2021-05-12-12-24-45.bpo-44113.DcgOqE.rst new file mode 100644 index 00000000000..45f67efa105 --- /dev/null +++ b/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 ` instead (:pep:`587`). diff --git a/Programs/_testembed.c b/Programs/_testembed.c index 0901933bfbb..21b24f7d51e 100644 --- a/Programs/_testembed.c +++ b/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);