Add sys.warn_default_encoding

Author: methane

Include/cpython/initconfig.h

@@ -134,6 +134,7 @@ typedef struct PyConfig {
     int isolated;
     int use_environment;
     int dev_mode;
+    int warn_default_encoding;
     int install_signal_handlers;
     int use_hash_seed;
     unsigned long hash_seed;

Include/internal/pycore_initconfig.h

@@ -102,13 +102,15 @@ typedef struct {
     int isolated;             /* -I option */
     int use_environment;      /* -E option */
     int dev_mode;             /* -X dev and PYTHONDEVMODE */
+    int warn_default_encoding; /* -X warndefaultencoding and PYTHONWARNDEFAULTENCODING */
 } _PyPreCmdline;
 
 #define _PyPreCmdline_INIT \
     (_PyPreCmdline){ \
         .use_environment = -1, \
         .isolated = -1, \
-        .dev_mode = -1}
+        .dev_mode = -1, \
+        .warn_default_encoding = -1}
 /* Note: _PyPreCmdline_INIT sets other fields to 0/NULL */
 
 extern void _PyPreCmdline_Clear(_PyPreCmdline *cmdline);

Lib/_pyio.py

@@ -45,14 +45,16 @@ def text_encoding(encoding, stacklevel=1):
     Helper function to choose the text encoding.
 
     When encoding is not None, just return it.
-    Otherwise, return the default text encoding ("locale" for now)
-    and raise a EncodingWarning in dev mode.
+    Otherwise, return the default text encoding (i.e. "locale").
+
+    This function emits EncodingWarning if *encoding* is None and
+    sys.flags.encoding_warning is true.
 
     This function can be used in APIs having encoding=None option.
     But please consider encoding="utf-8" for new APIs.
     """
     if encoding is None:
-        if sys.flags.dev_mode:
+        if sys.flags.warn_default_encoding:
             import warnings
             warnings.warn(
                     "'encoding' option is not specified. The default encoding "

Lib/test/test_io.py

@@ -4242,7 +4242,7 @@ def test_check_encoding_warning(self):
 
             pathlib.Path({filename!r}).read_text()  # line 8
         ''')
-        proc = assert_python_ok('-X', 'dev', '-c', code)
+        proc = assert_python_ok('-X', 'warn_default_encoding', '-c', code)
         warnings = proc.err.splitlines()
         self.assertEqual(len(warnings), 2)
         self.assertTrue(

Lib/test/test_sys.py

@@ -591,7 +591,8 @@ def test_sys_flags(self):
                  "inspect", "interactive", "optimize",
                  "dont_write_bytecode", "no_user_site", "no_site",
                  "ignore_environment", "verbose", "bytes_warning", "quiet",
-                 "hash_randomization", "isolated", "dev_mode", "utf8_mode")
+                 "hash_randomization", "isolated", "dev_mode", "utf8_mode",
+                 "warn_default_encoding")
         for attr in attrs:
             self.assertTrue(hasattr(sys.flags, attr), attr)
             attr_type = bool if attr == "dev_mode" else int

Modules/_io/_iomodule.c

@@ -516,8 +516,10 @@ _io.text_encoding
 Helper function to choose the text encoding.
 
 When encoding is not None, just return it.
-Otherwise, return the default text encoding ("locale" for now)
-and raise a EncodingWarning in dev mode.
+Otherwise, return the default text encoding (i.e. "locale").
+
+This function emits EncodingWarning if *encoding* is None and
+sys.flags.encoding_warning is true.
 
 This function can be used in APIs having encoding=None option.
 But please consider encoding="utf-8" for new APIs.
@@ -529,11 +531,9 @@ _io_text_encoding_impl(PyObject *module, PyObject *encoding, int stacklevel)
 {
     if (encoding == NULL || encoding == Py_None) {
         PyInterpreterState *interp = _PyInterpreterState_GET();
-        if (!_PyInterpreterState_GetConfig(interp)->dev_mode) {
+        if (_PyInterpreterState_GetConfig(interp)->warn_default_encoding) {
             PyErr_WarnEx(PyExc_EncodingWarning,
-                "'encoding' option is not specified. The default encoding "
-                "will be changed to 'utf-8' in the future",
-                stacklevel + 1);
+                         "'encoding' option is omitted", stacklevel + 1);
         }
         Py_INCREF(_PyIO_str_locale);
         return _PyIO_str_locale;

Modules/_io/textio.c

@@ -1125,10 +1125,9 @@ _io_TextIOWrapper___init___impl(textio *self, PyObject *buffer,
 
     if (encoding == NULL) {
         PyInterpreterState *interp = _PyInterpreterState_GET();
-        if (!_PyInterpreterState_GetConfig(interp)->dev_mode) {
-            PyErr_WarnEx(PyExc_DeprecationWarning,
-                "'encoding' option is not specified. The default encoding "
-                "will be changed to 'utf-8' in the future", 1);
+        if (_PyInterpreterState_GetConfig(interp)->warn_default_encoding) {
+            PyErr_WarnEx(PyExc_EncodingWarning,
+                         "'encoding' option is omitted", 1);
         }
     }
     else if (strcmp(encoding, "locale") == 0) {

Objects/exceptions.c

@@ -2406,13 +2406,6 @@ SimpleExtendsException(PyExc_Warning, UserWarning,
                        "Base class for warnings generated by user code.");
 
 
-/*
- *    EncodingWarning extends Warning
- */
-SimpleExtendsException(PyExc_Warning, EncodingWarning,
-                       "Base class for warnings about encodings.");
-
-
 /*
  *    DeprecationWarning extends Warning
  */
@@ -2428,6 +2421,13 @@ SimpleExtendsException(PyExc_Warning, PendingDeprecationWarning,
     "in the future.");
 
 
+/*
+ *    EncodingWarning extends Warning
+ */
+SimpleExtendsException(PyExc_DeprecationWarning, EncodingWarning,
+                       "Base class for warnings about encodings.");
+
+
 /*
  *    SyntaxWarning extends Warning
  */

Python/initconfig.c

@@ -94,6 +94,7 @@ static const char usage_3[] = "\
              otherwise activate automatically)\n\
          -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted at the\n\
              given directory instead of to the code tree\n\
+         -X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None'\n\
 \n\
 --check-hash-based-pycs always|default|never:\n\
     control how Python invalidates hash-based .pyc files\n\
@@ -129,7 +130,8 @@ static const char usage_6[] =
 "PYTHONBREAKPOINT: if this variable is set to 0, it disables the default\n"
 "   debugger. It can be set to the callable of your debugger of choice.\n"
 "PYTHONDEVMODE: enable the development mode.\n"
-"PYTHONPYCACHEPREFIX: root directory for bytecode cache (pyc) files.\n";
+"PYTHONPYCACHEPREFIX: root directory for bytecode cache (pyc) files.\n"
+"PYTHONWARNDEFAULTENCODING: enable opt-in EncodingWarning for 'encoding=None'.\n";
 
 #if defined(MS_WINDOWS)
 #  define PYTHONHOMEHELP "<prefix>\\python{major}{minor}"
@@ -589,6 +591,7 @@ config_check_consistency(const PyConfig *config)
     assert(config->isolated >= 0);
     assert(config->use_environment >= 0);
     assert(config->dev_mode >= 0);
+    assert(config->warn_default_encoding >= 0);
     assert(config->install_signal_handlers >= 0);
     assert(config->use_hash_seed >= 0);
     assert(config->hash_seed <= MAX_HASH_SEED);
@@ -690,6 +693,7 @@ _PyConfig_InitCompatConfig(PyConfig *config)
     config->isolated = -1;
     config->use_environment = -1;
     config->dev_mode = -1;
+    config->warn_default_encoding = -1;
     config->install_signal_handlers = 1;
     config->use_hash_seed = -1;
     config->faulthandler = -1;
@@ -765,6 +769,7 @@ PyConfig_InitIsolatedConfig(PyConfig *config)
     config->use_environment = 0;
     config->user_site_directory = 0;
     config->dev_mode = 0;
+    config->warn_default_encoding = 0;
     config->install_signal_handlers = 0;
     config->use_hash_seed = 0;
     config->faulthandler = 0;
@@ -873,6 +878,7 @@ _PyConfig_Copy(PyConfig *config, const PyConfig *config2)
     COPY_ATTR(isolated);
     COPY_ATTR(use_environment);
     COPY_ATTR(dev_mode);
+    COPY_ATTR(warn_default_encoding);
     COPY_ATTR(install_signal_handlers);
     COPY_ATTR(use_hash_seed);
     COPY_ATTR(hash_seed);
@@ -977,6 +983,7 @@ _PyConfig_AsDict(const PyConfig *config)
     SET_ITEM_INT(isolated);
     SET_ITEM_INT(use_environment);
     SET_ITEM_INT(dev_mode);
+    SET_ITEM_INT(warn_default_encoding);
     SET_ITEM_INT(install_signal_handlers);
     SET_ITEM_INT(use_hash_seed);
     SET_ITEM_UINT(hash_seed);
@@ -1249,6 +1256,7 @@ _PyConfig_FromDict(PyConfig *config, PyObject *dict)
     GET_UINT(isolated);
     GET_UINT(use_environment);
     GET_UINT(dev_mode);
+    GET_UINT(warn_default_encoding);
     GET_UINT(install_signal_handlers);
     GET_UINT(use_hash_seed);
     if (config_dict_get_ulong(dict, "hash_seed", &config->hash_seed) < 0) {
@@ -2136,6 +2144,10 @@ config_read(PyConfig *config, int compute_path_config)
         config->parse_argv = 2;
     }
 
+    if (config->warn_default_encoding < 0) {
+        config->warn_default_encoding = 0;
+    }
+
     return _PyStatus_OK();
 }
 

Python/preconfig.c

@@ -169,6 +169,7 @@ _PyPreCmdline_SetConfig(const _PyPreCmdline *cmdline, PyConfig *config)
     COPY_ATTR(isolated);
     COPY_ATTR(use_environment);
     COPY_ATTR(dev_mode);
+    COPY_ATTR(warn_default_encoding);
     return _PyStatus_OK();
 
 #undef COPY_ATTR
@@ -257,9 +258,21 @@ _PyPreCmdline_Read(_PyPreCmdline *cmdline, const PyPreConfig *preconfig)
         cmdline->dev_mode = 0;
     }
 
+    // warn_default_encoding
+    if ((cmdline->warn_default_encoding < 0)
+        && (_Py_get_xoption(&cmdline->xoptions, L"warn_default_encoding")
+            || _Py_GetEnv(cmdline->use_environment, "PYTHONWARNDEFAULTENCODING")))
+    {
+        cmdline->warn_default_encoding = 1;
+    }
+    if (cmdline->warn_default_encoding < 0) {
+        cmdline->warn_default_encoding = 0;
+    }
+
     assert(cmdline->use_environment >= 0);
     assert(cmdline->isolated >= 0);
     assert(cmdline->dev_mode >= 0);
+    assert(cmdline->warn_default_encoding >= 0);
 
     return _PyStatus_OK();
 }

Python/sysmodule.c

@@ -2506,14 +2506,15 @@ static PyStructSequence_Field flags_fields[] = {
     {"isolated",                "-I"},
     {"dev_mode",                "-X dev"},
     {"utf8_mode",               "-X utf8"},
+    {"warn_default_encoding",   "-X warndefaultencoding"},
     {0}
 };
 
 static PyStructSequence_Desc flags_desc = {
     "sys.flags",        /* name */
     flags__doc__,       /* doc */
     flags_fields,       /* fields */
-    15
+    16
 };
 
 static int
@@ -2552,6 +2553,7 @@ set_flags_from_config(PyObject *flags, PyThreadState *tstate)
     SetFlag(config->use_hash_seed == 0 || config->hash_seed != 0);
     SetFlag(config->isolated);
     SetFlagObj(PyBool_FromLong(config->dev_mode));
+    SetFlagObj(PyBool_FromLong(config->warn_default_encoding));
     SetFlag(preconfig->utf8_mode);
 #undef SetFlagObj
 #undef SetFlag