gh-77782: Deprecate global configuration variable (#93943)

Deprecate global configuration variable like
Py_IgnoreEnvironmentFlag: the Py_InitializeFromConfig() API should be
instead.

Fix declaration of Py_GETENV(): use PyAPI_FUNC(), not PyAPI_DATA().

8 files changed, 96 insertions, 28 deletions

diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 99b8a14..b7d7eec 100644
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -257,6 +257,35 @@ Porting to Python 3.12
 Deprecated
 ----------
 
+* Deprecate global configuration variable:
+
+  * :c:var:`Py_DebugFlag`: use :c:member:`PyConfig.parser_debug`
+  * :c:var:`Py_VerboseFlag`: use :c:member:`PyConfig.verbose`
+  * :c:var:`Py_QuietFlag`: use :c:member:`PyConfig.quiet`
+  * :c:var:`Py_InteractiveFlag`: use :c:member:`PyConfig.interactive`
+  * :c:var:`Py_InspectFlag`: use :c:member:`PyConfig.inspect`
+  * :c:var:`Py_OptimizeFlag`: use :c:member:`PyConfig.optimization_level`
+  * :c:var:`Py_NoSiteFlag`: use :c:member:`PyConfig.site_import`
+  * :c:var:`Py_BytesWarningFlag`: use :c:member:`PyConfig.bytes_warning`
+  * :c:var:`Py_FrozenFlag`: use :c:member:`PyConfig.pathconfig_warnings`
+  * :c:var:`Py_IgnoreEnvironmentFlag`: use :c:member:`PyConfig.use_environment`
+  * :c:var:`Py_DontWriteBytecodeFlag`: use :c:member:`PyConfig.write_bytecode`
+  * :c:var:`Py_NoUserSiteDirectory`: use :c:member:`PyConfig.user_site_directory`
+  * :c:var:`Py_UnbufferedStdioFlag`: use :c:member:`PyConfig.buffered_stdio`
+  * :c:var:`Py_HashRandomizationFlag`: use :c:member:`PyConfig.use_hash_seed`
+    and :c:member:`PyConfig.hash_seed`
+  * :c:var:`Py_IsolatedFlag`: use :c:member:`PyConfig.isolated`
+  * :c:var:`Py_LegacyWindowsFSEncodingFlag`: use :c:member:`PyConfig.legacy_windows_fs_encoding`
+  * :c:var:`Py_LegacyWindowsStdioFlag`: use :c:member:`PyConfig.legacy_windows_stdio`
+  * :c:var:`Py_FileSystemDefaultEncoding`: use :c:member:`PyConfig.filesystem_encoding`
+  * :c:var:`Py_FileSystemDefaultEncodeErrors`: use :c:member:`PyConfig.filesystem_errors`
+  * :c:var:`Py_UTF8Mode`: use :c:member:`PyPreConfig.utf8_mode` (see :c:func:`Py_PreInitialize`)
+
+  The :c:func:`Py_InitializeFromConfig` API should be used with
+  :c:type:`PyConfig` instead.
+  (Contributed by Victor Stinner in :gh:`77782`.)
+
+
 Removed
 -------
 
diff --git a/Include/cpython/pydebug.h b/Include/cpython/pydebug.h
index cab799f..f6ebd99 100644
--- a/Include/cpython/pydebug.h
+++ b/Include/cpython/pydebug.h
@@ -5,31 +5,31 @@
 extern "C" {
 #endif
 
-PyAPI_DATA(int) Py_DebugFlag;
-PyAPI_DATA(int) Py_VerboseFlag;
-PyAPI_DATA(int) Py_QuietFlag;
-PyAPI_DATA(int) Py_InteractiveFlag;
-PyAPI_DATA(int) Py_InspectFlag;
-PyAPI_DATA(int) Py_OptimizeFlag;
-PyAPI_DATA(int) Py_NoSiteFlag;
-PyAPI_DATA(int) Py_BytesWarningFlag;
-PyAPI_DATA(int) Py_FrozenFlag;
-PyAPI_DATA(int) Py_IgnoreEnvironmentFlag;
-PyAPI_DATA(int) Py_DontWriteBytecodeFlag;
-PyAPI_DATA(int) Py_NoUserSiteDirectory;
-PyAPI_DATA(int) Py_UnbufferedStdioFlag;
-PyAPI_DATA(int) Py_HashRandomizationFlag;
-PyAPI_DATA(int) Py_IsolatedFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_DebugFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_VerboseFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_QuietFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_InteractiveFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_InspectFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_OptimizeFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_NoSiteFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_BytesWarningFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_FrozenFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_IgnoreEnvironmentFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_DontWriteBytecodeFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_NoUserSiteDirectory;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_UnbufferedStdioFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_HashRandomizationFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_IsolatedFlag;
 
 #ifdef MS_WINDOWS
-PyAPI_DATA(int) Py_LegacyWindowsFSEncodingFlag;
-PyAPI_DATA(int) Py_LegacyWindowsStdioFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_LegacyWindowsFSEncodingFlag;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_LegacyWindowsStdioFlag;
 #endif
 
 /* this is a wrapper around getenv() that pays attention to
    Py_IgnoreEnvironmentFlag.  It should be used for getting variables like
    PYTHONPATH and PYTHONHOME from the environment */
-PyAPI_DATA(char*) Py_GETENV(const char *name);
+PyAPI_FUNC(char*) Py_GETENV(const char *name);
 
 #ifdef __cplusplus
 }
diff --git a/Include/cpython/pystate.h b/Include/cpython/pystate.h
index 2bd4606..cc3c3ea 100644
--- a/Include/cpython/pystate.h
+++ b/Include/cpython/pystate.h
@@ -279,7 +279,10 @@ PyAPI_FUNC(const PyConfig*) _PyInterpreterState_GetConfig(PyInterpreterState *in
    for example.
 
    Python must be preinitialized to call this method.
-   The caller must hold the GIL. */
+   The caller must hold the GIL.
+
+   Once done with the configuration, PyConfig_Clear() must be called to clear
+   it. */
 PyAPI_FUNC(int) _PyInterpreterState_GetConfigCopy(
     struct PyConfig *config);
 
diff --git a/Include/fileobject.h b/Include/fileobject.h
index 4c983e7..02bd7c9 100644
--- a/Include/fileobject.h
+++ b/Include/fileobject.h
@@ -19,14 +19,14 @@ PyAPI_FUNC(int) PyObject_AsFileDescriptor(PyObject *);
 /* The default encoding used by the platform file system APIs
    If non-NULL, this is different than the default encoding for strings
 */
-PyAPI_DATA(const char *) Py_FileSystemDefaultEncoding;
+Py_DEPRECATED(3.12) PyAPI_DATA(const char *) Py_FileSystemDefaultEncoding;
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03060000
-PyAPI_DATA(const char *) Py_FileSystemDefaultEncodeErrors;
+Py_DEPRECATED(3.12) PyAPI_DATA(const char *) Py_FileSystemDefaultEncodeErrors;
 #endif
 PyAPI_DATA(int) Py_HasFileSystemDefaultEncoding;
 
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03070000
-PyAPI_DATA(int) Py_UTF8Mode;
+Py_DEPRECATED(3.12) PyAPI_DATA(int) Py_UTF8Mode;
 #endif
 
 /* A routine to check if a file descriptor can be select()-ed. */
diff --git a/Misc/NEWS.d/next/C API/2022-05-23-12-31-04.gh-issue-77782.ugC8dn.rst b/Misc/NEWS.d/next/C API/2022-05-23-12-31-04.gh-issue-77782.ugC8dn.rst
new file mode 100644
index 0000000..d212f6b
--- /dev/null
+++ b/Misc/NEWS.d/next/C API/2022-05-23-12-31-04.gh-issue-77782.ugC8dn.rst
@@ -0,0 +1,3 @@
+Deprecate global configuration variable like
+:c:var:`Py_IgnoreEnvironmentFlag`: the :c:func:`Py_InitializeFromConfig` API
+should be instead. Patch by Victor Stinner.
diff --git a/Modules/main.c b/Modules/main.c
index cca669b..90f2372 100644
--- a/Modules/main.c
+++ b/Modules/main.c
@@ -479,12 +479,23 @@ error:
 }
 
 
+static void
+pymain_set_inspect(PyConfig *config, int inspect)
+{
+    config->inspect = inspect;
+_Py_COMP_DIAG_PUSH
+_Py_COMP_DIAG_IGNORE_DEPR_DECLS
+    Py_InspectFlag = inspect;
+_Py_COMP_DIAG_POP
+}
+
+
 static int
 pymain_run_stdin(PyConfig *config)
 {
     if (stdin_is_interactive(config)) {
-        config->inspect = 0;
-        Py_InspectFlag = 0; /* do exit on SystemExit */
+        // do exit on SystemExit
+        pymain_set_inspect(config, 0);
 
         int exitcode;
         if (pymain_run_startup(config, &exitcode)) {
@@ -517,16 +528,14 @@ pymain_repl(PyConfig *config, int *exitcode)
     /* Check this environment variable at the end, to give programs the
        opportunity to set it from Python. */
     if (!config->inspect && _Py_GetEnv(config->use_environment, "PYTHONINSPECT")) {
-        config->inspect = 1;
-        Py_InspectFlag = 1;
+        pymain_set_inspect(config, 1);
     }
 
     if (!(config->inspect && stdin_is_interactive(config) && config_run_code(config))) {
         return;
     }
 
-    config->inspect = 0;
-    Py_InspectFlag = 0;
+    pymain_set_inspect(config, 0);
     if (pymain_run_interactive_hook(exitcode)) {
         return;
     }
diff --git a/Python/initconfig.c b/Python/initconfig.c
index e5b8787..62f1f67 100644
--- a/Python/initconfig.c
+++ b/Python/initconfig.c
@@ -201,6 +201,8 @@ int Py_LegacyWindowsStdioFlag = 0; /* Uses FileIO instead of WindowsConsoleIO */
 static PyObject *
 _Py_GetGlobalVariablesAsDict(void)
 {
+_Py_COMP_DIAG_PUSH
+_Py_COMP_DIAG_IGNORE_DEPR_DECLS
     PyObject *dict, *obj;
 
     dict = PyDict_New();
@@ -267,15 +269,19 @@ fail:
 #undef SET_ITEM
 #undef SET_ITEM_INT
 #undef SET_ITEM_STR
+_Py_COMP_DIAG_POP
 }
 
 char*
 Py_GETENV(const char *name)
 {
+_Py_COMP_DIAG_PUSH
+_Py_COMP_DIAG_IGNORE_DEPR_DECLS
     if (Py_IgnoreEnvironmentFlag) {
         return NULL;
     }
     return getenv(name);
+_Py_COMP_DIAG_POP
 }
 
 /* --- PyStatus ----------------------------------------------- */
@@ -1443,6 +1449,8 @@ config_get_env_dup(PyConfig *config,
 static void
 config_get_global_vars(PyConfig *config)
 {
+_Py_COMP_DIAG_PUSH
+_Py_COMP_DIAG_IGNORE_DEPR_DECLS
     if (config->_config_init != _PyConfig_INIT_COMPAT) {
         /* Python and Isolated configuration ignore global variables */
         return;
@@ -1478,6 +1486,7 @@ config_get_global_vars(PyConfig *config)
 
 #undef COPY_FLAG
 #undef COPY_NOT_FLAG
+_Py_COMP_DIAG_POP
 }
 
 
@@ -1485,6 +1494,8 @@ config_get_global_vars(PyConfig *config)
 static void
 config_set_global_vars(const PyConfig *config)
 {
+_Py_COMP_DIAG_PUSH
+_Py_COMP_DIAG_IGNORE_DEPR_DECLS
 #define COPY_FLAG(ATTR, VAR) \
         if (config->ATTR != -1) { \
             VAR = config->ATTR; \
@@ -1519,6 +1530,7 @@ config_set_global_vars(const PyConfig *config)
 
 #undef COPY_FLAG
 #undef COPY_NOT_FLAG
+_Py_COMP_DIAG_POP
 }
 
 
diff --git a/Python/preconfig.c b/Python/preconfig.c
index c30c758..77a86d6 100644
--- a/Python/preconfig.c
+++ b/Python/preconfig.c
@@ -24,6 +24,8 @@ int _Py_HasFileSystemDefaultEncodeErrors = 0;
 void
 _Py_ClearFileSystemEncoding(void)
 {
+_Py_COMP_DIAG_PUSH
+_Py_COMP_DIAG_IGNORE_DEPR_DECLS
     if (!Py_HasFileSystemDefaultEncoding && Py_FileSystemDefaultEncoding) {
         PyMem_RawFree((char*)Py_FileSystemDefaultEncoding);
         Py_FileSystemDefaultEncoding = NULL;
@@ -32,6 +34,7 @@ _Py_ClearFileSystemEncoding(void)
         PyMem_RawFree((char*)Py_FileSystemDefaultEncodeErrors);
         Py_FileSystemDefaultEncodeErrors = NULL;
     }
+_Py_COMP_DIAG_POP
 }
 
 
@@ -56,11 +59,14 @@ _Py_SetFileSystemEncoding(const char *encoding, const char *errors)
 
     _Py_ClearFileSystemEncoding();
 
+_Py_COMP_DIAG_PUSH
+_Py_COMP_DIAG_IGNORE_DEPR_DECLS
     Py_FileSystemDefaultEncoding = encoding2;
     Py_HasFileSystemDefaultEncoding = 0;
 
     Py_FileSystemDefaultEncodeErrors = errors2;
     _Py_HasFileSystemDefaultEncodeErrors = 0;
+_Py_COMP_DIAG_POP
     return 0;
 }
 
@@ -472,6 +478,8 @@ preconfig_get_global_vars(PyPreConfig *config)
         config->ATTR = !(VALUE); \
     }
 
+_Py_COMP_DIAG_PUSH
+_Py_COMP_DIAG_IGNORE_DEPR_DECLS
     COPY_FLAG(isolated, Py_IsolatedFlag);
     COPY_NOT_FLAG(use_environment, Py_IgnoreEnvironmentFlag);
     if (Py_UTF8Mode > 0) {
@@ -480,6 +488,7 @@ preconfig_get_global_vars(PyPreConfig *config)
 #ifdef MS_WINDOWS
     COPY_FLAG(legacy_windows_fs_encoding, Py_LegacyWindowsFSEncodingFlag);
 #endif
+_Py_COMP_DIAG_POP
 
 #undef COPY_FLAG
 #undef COPY_NOT_FLAG
@@ -498,12 +507,15 @@ preconfig_set_global_vars(const PyPreConfig *config)
         VAR = !config->ATTR; \
     }
 
+_Py_COMP_DIAG_PUSH
+_Py_COMP_DIAG_IGNORE_DEPR_DECLS
     COPY_FLAG(isolated, Py_IsolatedFlag);
     COPY_NOT_FLAG(use_environment, Py_IgnoreEnvironmentFlag);
 #ifdef MS_WINDOWS
     COPY_FLAG(legacy_windows_fs_encoding, Py_LegacyWindowsFSEncodingFlag);
 #endif
     COPY_FLAG(utf8_mode, Py_UTF8Mode);
+_Py_COMP_DIAG_POP
 
 #undef COPY_FLAG
 #undef COPY_NOT_FLAG