Use separate flag thread_safe_warnings.

python · nascheme · Apr 9, 2025 · Dec 28, 2024 · Dec 21, 2024 · Feb 7, 2025
commit 9e955dc723d60d1f0d1017781fa098579f83d1bb
diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
@@ -635,17 +635,18 @@
 Thread-safety of Context Managers
 ---------------------------------
 
 The behavior of :class:`catch_warnings` context manager depends on the value
-of the :data:`sys.flags.inherit_context` flag.  Being thread-safe means that
-behavior is predictable in a multi-threaded program.  For free-threaded
-builds, the flag defaults to true, and false otherwise.
+of the :data:`sys.flags.thread_safe_warnings` flag.  If the flag is true, the
+context manager behaves in a thread-safe fashion and otherwise not.  Being
+thread-safe means that behavior is predictable in a multi-threaded program.
+For free-threaded builds, the flag defaults to true, and false otherwise.
 
-If the :data:`~sys.flags.inherit_context` flag is false, then
-:class:`catch_warnings` will manipulate the global attributes of the
+If the :data:`~sys.flags.thread_safe_warnings` flag is false, then
+:class:`catch_warnings` will modify the global attributes of the
 :mod:`warnings` module.  This is not thread-safe.  If two or more threads use
 the context manager at the same time, the behavior is undefined.
 
-If the flag is true, :class:`catch_warnings` will not manipulate global
+If the flag is true, :class:`catch_warnings` will not modify global
 attributes and will instead use a :class:`~contextvars.ContextVar` to
 store the newly established warning filtering state.  A context variable
 provides thread-local storage and it makes the use of :class:`catch_warnings`
@@ -661,21 +662,25 @@
 property in the context variable.  In this case, the :func:`showwarning`
 function will not be restored when exiting the context handler.
 
-The :data:`~sys.flags.inherit_context` flag can be set the :option:`-X
-inherit_context <-X>` command-line option or by the
-:envvar:`PYTHON_INHERIT_CONTEXT` environment variable.
+The :data:`~sys.flags.thread_safe_warnings` flag can be set the :option:`-X
+thread_safe_warnings<-X>` command-line option or by the
+:envvar:`PYTHON_THREAD_SAFE_WARNINGS` environment variable.
 
     .. note::
 
-        When the :data:`~sys.flags.inherit_context` flag true, it also causes
-        threads created by :class:`threading.Thread` to start with a copy of
-        the context variables from the thread starting it.  This means that
-        context established by using :class:`catch_warnings` in one thread
-        will also apply to new threads started by it.  If the new thread creates
-        a new context with :class:`catch_warnings`, that context only applies to
-        that thread.
+        It is likely that most programs that desire thread-safe
+        behaviour of the warnings module will also want to set the
+        :data:`~sys.flags.thread_inherit_context` flag to true.  That flag
+        causes threads created by :class:`threading.Thread` to start
+        with a copy of the context variables from the thread starting
+        it.  When true, the context established by :class:`catch_warnings`
+        in one thread will also apply to new threads started by it.  If false,
+        new threads will start with an empty warnings context variable,
+        meaning that only the filters in :data:`warnings.filters` will be
+        active.
 
 .. versionchanged:: 3.14
 
-   Added the :data:`sys.flags.inherit_context` flag and the use of a context
-   variable for :class:`catch_warnings` if the flag is true.
+   Added the :data:`sys.flags.thread_safe_warnings` flag and the use of a
+   context variable for :class:`catch_warnings` if the flag is true.  Previous
+   versions of Python acted as if the flag was always set to false.
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
@@ -637,6 +637,14 @@ Miscellaneous options
 
      .. versionadded:: 3.14
 
+   * :samp:`-X thread_safe_warnings={0,1}` causes the
+     :class:`warnings.catch_warnings` context manager to use a
+     :class:`~contextvars.ContextVar` to store warnings filter state.  If
+     unset, the value of this option defaults to ``1`` on free-threaded builds
+     and to ``0`` otherwise.  See also :envvar:`PYTHON_THREAD_SAFE_WARNINGS`.
+
+     .. versionadded:: 3.14
+
    It also allows passing arbitrary values and retrieving them through the
    :data:`sys._xoptions` dictionary.
 
@@ -1240,6 +1248,16 @@ conflict.
 
    .. versionadded:: 3.14
 
+.. envvar:: PYTHON_THREAD_SAFE_WARNINGS
+
+   If set to ``1`` then the :class:`warnings.catch_warnings` context
+   manager will use a :class:`~contextvars.ContextVar` to store warnings
+   filter state.  If unset, this variable defaults to ``1`` on
+   free-threaded builds and to ``0`` otherwise.  See :option:`-X
+   thread_safe_warnings<-X>`.
+
+   .. versionadded:: 3.14
+
 Debug-mode variables
 ~~~~~~~~~~~~~~~~~~~~
 

@@ -180,6 +180,7 @@ typedef struct PyConfig {
     int safe_path;
     int int_max_str_digits;
     int thread_inherit_context;
+    int thread_safe_warnings;
 #ifdef __APPLE__
     int use_system_logger;
 #endif

diff --git a/Lib/test/test_capi/test_config.py b/Lib/test/test_capi/test_config.py
@@ -56,6 +56,7 @@ def test_config_get(self):
             ("hash_seed", int, None),
             ("home", str | None, None),
             ("thread_inherit_context", int, None),
+            ("thread_safe_warnings", int, None),
             ("import_time", bool, None),
             ("inspect", bool, None),
             ("install_signal_handlers", bool, None),
@@ -171,7 +172,7 @@ def test_config_get_sys_flags(self):
             ("warn_default_encoding", "warn_default_encoding", False),
             ("safe_path", "safe_path", False),
             ("int_max_str_digits", "int_max_str_digits", False),
-            # "gil" and "thread_inherit_context" are tested below
+            # "gil", "thread_inherit_context" and "thread_safe_warnings" are tested below
         ):
             with self.subTest(flag=flag, name=name, negate=negate):
                 value = config_get(name)
@@ -191,6 +192,9 @@ def test_config_get_sys_flags(self):
         expected_inherit_context = 1 if support.Py_GIL_DISABLED else 0
         self.assertEqual(sys.flags.thread_inherit_context, expected_inherit_context)
 
+        expected_safe_warnings = 1 if support.Py_GIL_DISABLED else 0
+        self.assertEqual(sys.flags.thread_safe_warnings, expected_safe_warnings)
+
     def test_config_get_non_existent(self):
         # Test PyConfig_Get() on non-existent option name
         config_get = _testcapi.config_get

diff --git a/Lib/test/test_embed.py b/Lib/test/test_embed.py
@@ -60,10 +60,8 @@
     PLATSTDLIB_LANDMARK = (f'{sys.platlibdir}/python{VERSION_MAJOR}.'
                            f'{VERSION_MINOR}{ABI_THREAD}/lib-dynload')
 
-if support.Py_GIL_DISABLED:
-    DEFAULT_THREAD_INHERIT_CONTEXT = 1
-else:
-    DEFAULT_THREAD_INHERIT_CONTEXT = 0
+DEFAULT_THREAD_INHERIT_CONTEXT = 1 if support.Py_GIL_DISABLED else 0
+DEFAULT_THREAD_SAFE_WARNINGS = 1 if support.Py_GIL_DISABLED else 0
 
 # If we are running from a build dir, but the stdlib has been installed,
 # some tests need to expect different results.
@@ -591,6 +589,7 @@ class InitConfigTests(EmbeddingTestsMixin, unittest.TestCase):
         'perf_profiling': 0,
         'import_time': False,
         'thread_inherit_context': DEFAULT_THREAD_INHERIT_CONTEXT,
+        'thread_safe_warnings': DEFAULT_THREAD_SAFE_WARNINGS,
         'code_debug_ranges': True,
         'show_ref_count': False,
         'dump_refs': False,

diff --git a/Lib/test/test_sys.py b/Lib/test/test_sys.py
@@ -1845,9 +1845,10 @@ def test_pythontypes(self):
         # symtable entry
         # XXX
         # sys.flags
-        # FIXME: The +2 is for the 'gil' and 'thread_inherit_context' flags and
-        # will not be necessary once gh-122575 is fixed
-        check(sys.flags, vsize('') + self.P * (2 + len(sys.flags)))
+        # FIXME: The +3 is for the 'gil', 'thread_inherit_context' and
+        # 'thread_safe_warnings' flags and will not be necessary once
+        # gh-122575 is fixed
+        check(sys.flags, vsize('') + self.P * (3 + len(sys.flags)))
 
     def test_asyncgen_hooks(self):
         old = sys.get_asyncgen_hooks()

diff --git a/Lib/warnings.py b/Lib/warnings.py
@@ -11,7 +11,7 @@
 # If true, catch_warnings() will use a context var to hold the modified
 # filters list.  Otherwise, catch_warnings() will operate on the 'filters'
 # global of the warnings module.
-_use_context = sys.flags.inherit_context
+_use_context = sys.flags.thread_safe_warnings
 
 class _Context:
     def __init__(self, filters):

diff --git a/Misc/NEWS.d/next/Library/2025-02-11-10-22-11.gh-issue-128384.jyWEkA.rst b/Misc/NEWS.d/next/Library/2025-02-11-10-22-11.gh-issue-128384.jyWEkA.rst
@@ -1,7 +1,7 @@
-Make :class:`warnings.catch_warnings` use a context variable for holding the
-warning filtering state if the :data:`sys.flags.inherit_context` flag is set
-to true.  This makes using the context manager thread-safe in multi-threaded
-programs.  The flag is true by default in free-threaded builds and is
-otherwise false.  The default value of the flag can be overridden by the the
-:option:`-X inherit_context <-X>` command-line option or by the
-:envvar:`PYTHON_INHERIT_CONTEXT` environment variable.
+Make :class:`warnings.catch_warnings` use a context variable for holding
+the warning filtering state if the :data:`sys.flags.thread_safe_warnings`
+flag is set to true.  This makes using the context manager thread-safe in
+multi-threaded programs.  The flag is true by default in free-threaded builds
+and is otherwise false.  The value of the flag can be overridden by the
+the :option:`-X thread_safe_warnings <-X>` command-line option or by the
+:envvar:`PYTHON_THREAD_SAFE_WARNINGS` environment variable.
@@ -142,6 +142,7 @@ static const PyConfigSpec PYCONFIG_SPEC[] = {
     SPEC(hash_seed, ULONG, READ_ONLY, NO_SYS),
     SPEC(home, WSTR_OPT, READ_ONLY, NO_SYS),
     SPEC(thread_inherit_context, INT, READ_ONLY, NO_SYS),
+    SPEC(thread_safe_warnings, INT, READ_ONLY, NO_SYS),
     SPEC(import_time, BOOL, READ_ONLY, NO_SYS),
     SPEC(install_signal_handlers, BOOL, READ_ONLY, NO_SYS),
     SPEC(isolated, BOOL, READ_ONLY, NO_SYS),  // sys.flags.isolated
@@ -329,6 +330,12 @@ The following implementation-specific options are available:\n\
 -X thread_inherit_context=[0|1]: enable (1) or disable (0) threads inheriting\n\
          context vars by default; enabled by default in the free-threaded\n\
          build and disabled otherwise; also PYTHON_THREAD_INHERIT_CONTEXT\n\
+-X thread_safe_warnings=[0|1]: if true (1) then the warnings module will\n\
+         use a context variable to store warnings filtering state, making it\n\
+         safe to use in multi-threaded programs; if false (0) then the\n\
+         warnings module will use module globals, which is not thread-safe;\n\
+         set to true for free-threaded builds and false otherwise; also\n\
+         PYTHON_THREAD_SAFE_WARNINGS\n\
 -X tracemalloc[=N]: trace Python memory allocations; N sets a traceback limit\n \
          of N frames (default: 1); also PYTHONTRACEMALLOC=N\n\
 -X utf8[=0|1]: enable (1) or disable (0) UTF-8 mode; also PYTHONUTF8\n\
@@ -416,8 +423,10 @@ static const char usage_envvars[] =
 #ifdef Py_GIL_DISABLED
 "PYTHON_TLBC     : when set to 0, disables thread-local bytecode (-X tlbc)\n"
 #endif
-"PYTHON_THREAD_INHERIT_CONTEXT: threads inherit context vars if 1\n"
+"PYTHON_THREAD_INHERIT_CONTEXT: if true (1), threads inherit context vars\n"
 "                   (-X thread_inherit_context)\n"
+"PYTHON_THREAD_SAFE_WARNINGS: if true (1), enable thread-safe warnings module\n"
+"                   behaviour (-X thread_safe_warnings)\n"
 "PYTHONTRACEMALLOC: trace Python memory allocations (-X tracemalloc)\n"
 "PYTHONUNBUFFERED: disable stdout/stderr buffering (-u)\n"
 "PYTHONUTF8      : control the UTF-8 mode (-X utf8)\n"
@@ -894,6 +903,7 @@ config_check_consistency(const PyConfig *config)
     // config->use_frozen_modules is initialized later
     // by _PyConfig_InitImportConfig().
     assert(config->thread_inherit_context >= 0);
+    assert(config->thread_safe_warnings >= 0);
 #ifdef __APPLE__
     assert(config->use_system_logger >= 0);
 #endif
@@ -1001,8 +1011,10 @@ _PyConfig_InitCompatConfig(PyConfig *config)
     config->cpu_count = -1;
 #ifdef Py_GIL_DISABLED
     config->thread_inherit_context = 1;
+    config->thread_safe_warnings = 1;
 #else
     config->thread_inherit_context = 0;
+    config->thread_safe_warnings = 0;
 #endif
 #ifdef __APPLE__
     config->use_system_logger = 0;
@@ -1038,8 +1050,10 @@ config_init_defaults(PyConfig *config)
 #endif
 #ifdef Py_GIL_DISABLED
     config->thread_inherit_context = 1;
+    config->thread_safe_warnings = 1;
 #else
     config->thread_inherit_context = 0;
+    config->thread_safe_warnings = 0;
 #endif
 #ifdef __APPLE__
     config->use_system_logger = 0;
@@ -1935,6 +1949,32 @@ config_init_thread_inherit_context(PyConfig *config)
     return _PyStatus_OK();
 }
 
+static PyStatus
+config_init_thread_safe_warnings(PyConfig *config)
+{
+    const char *env = config_get_env(config, "PYTHON_THREAD_SAFE_WARNINGS");
+    if (env) {
+        int enabled;
+        if (_Py_str_to_int(env, &enabled) < 0 || (enabled < 0) || (enabled > 1)) {
+            return _PyStatus_ERR(
+                "PYTHON_THREAD_SAFE_WARNINGS=N: N is missing or invalid");
+        }
+        config->thread_safe_warnings = enabled;
+    }
+
+    const wchar_t *xoption = config_get_xoption(config, L"thread_safe_warnings");
+    if (xoption) {
+        int enabled;
+        const wchar_t *sep = wcschr(xoption, L'=');
+        if (!sep || (config_wstr_to_int(sep + 1, &enabled) < 0) || (enabled < 0) || (enabled > 1)) {
+            return _PyStatus_ERR(
+                "-X thread_safe_warnings=n: n is missing or invalid");
+        }
+        config->thread_safe_warnings = enabled;
+    }
+    return _PyStatus_OK();
+}
+
 static PyStatus
 config_init_tlbc(PyConfig *config)
 {
@@ -2219,6 +2259,11 @@ config_read_complex_options(PyConfig *config)
         return status;
     }
 
+    status = config_init_thread_safe_warnings(config);
+    if (_PyStatus_EXCEPTION(status)) {
+        return status;
+    }
+
     status = config_init_tlbc(config);
     if (_PyStatus_EXCEPTION(status)) {
         return status;

@@ -3142,6 +3142,7 @@ static PyStructSequence_Field flags_fields[] = {
     {"int_max_str_digits",      "-X int_max_str_digits"},
     {"gil",                     "-X gil"},
     {"thread_inherit_context",  "-X thread_inherit_context"},
+    {"thread_safe_warnings",    "-X thread_safe_warnings"},
     {0}
 };
 
@@ -3246,6 +3247,7 @@ set_flags_from_config(PyInterpreterState *interp, PyObject *flags)
     SetFlagObj(PyLong_FromLong(1));
 #endif
     SetFlag(config->thread_inherit_context);
+    SetFlag(config->thread_safe_warnings);
 #undef SetFlagObj
 #undef SetFlag
     return 0;