Rename flag to 'context_aware_warnings'.

python · nascheme · Apr 9, 2025 · Dec 28, 2024 · Dec 21, 2024 · Feb 7, 2025
commit 983e7ee7272244de3ff8d4e2415ee7e37dccd5a2
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
@@ -602,9 +602,9 @@ always available. Unless explicitly noted otherwise, all variables are read-only
         - :option:`-X thread_inherit_context <-X>` and
           :envvar:`PYTHON_THREAD_INHERIT_CONTEXT`
 
-      * - .. attribute:: flags.thread_safe_warnings
+      * - .. attribute:: flags.context_aware_warnings
         - :option:`-X thread_inherit_context <-X>` and
-          :envvar:`PYTHON_THREAD_SAFE_WARNINGS`
+          :envvar:`PYTHON_CONTEXT_AWARE_WARNINGS`
 
 
    .. versionchanged:: 3.2
@@ -640,7 +640,7 @@ always available. Unless explicitly noted otherwise, all variables are read-only
       Added the ``thread_inherit_context`` attribute.
 
    .. versionchanged:: 3.14
-      Added the ``thread_safe_warnings`` attribute.
+      Added the ``context_aware_warnings`` attribute.
 
 
 .. data:: float_info

diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
@@ -328,9 +328,9 @@ of deprecated code.
 
     .. note::
 
-        See :ref:`warning-thread-safe` for details on the thread-safety of the
-        :class:`catch_warnings` context manager when used in multi-threaded
-        programs.
+        See :ref:`warning-concurrent-safe` for details on the
+        concurrency-safety of the :class:`catch_warnings` context manager when
+        used in programs using multiple threads or async functions.
 
 .. _warning-testing:
 
@@ -370,9 +370,9 @@ results.
 
     .. note::
 
-        See :ref:`warning-thread-safe` for details on the thread-safety of the
-        :class:`catch_warnings` context manager when used in multi-threaded
-        programs.
+        See :ref:`warning-concurrent-safe` for details on the
+        concurrency-safety of the :class:`catch_warnings` context manager when
+        used in programs using multiple threads or async functions.
 
 When testing multiple operations that raise the same kind of warning, it
 is important to test them in a manner that confirms each operation is raising
@@ -620,31 +620,35 @@ Available Context Managers
 
     .. note::
 
-        See :ref:`warning-thread-safe` for details on the thread-safety of the
-        :class:`catch_warnings` context manager when used in multi-threaded
-        programs.
+        See :ref:`warning-concurrent-safe` for details on the
+        concurrency-safety of the :class:`catch_warnings` context manager when
+        used in programs using multiple threads or async functions.
 
 
     .. versionchanged:: 3.11
 
         Added the *action*, *category*, *lineno*, and *append* parameters.
 
 
-.. _warning-thread-safe:
+.. _warning-concurrent-safe:
 
-Thread-safety of Context Managers
----------------------------------
+Concurrent safety of Context Managers
+-------------------------------------
 
-The behavior of :class:`catch_warnings` context manager depends on the value
-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.
+The behavior of :class:`catch_warnings` context manager depends on the
+:data:`sys.flags.context_aware_warnings` flag.  If the flag is true, the
+context manager behaves in a concurrent-safe fashion and otherwise not.
+Concurrent-safe means that it is both thread-safe and safe to use within
+:ref:`asyncio coroutines <coroutine>` and tasks.  Being thread-safe means
+that behavior is predictable in a multi-threaded program.  The flag defaults
+to true for free-threaded builds and false otherwise.
 
-If the :data:`~sys.flags.thread_safe_warnings` flag is false, then
+If the :data:`~sys.flags.context_aware_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.
+:mod:`warnings` module.  This is not safe if used within a concurrent program
+(using multiple threads or using asyncio coroutines).  For example, if two
+or more threads use the :class:`catch_warnings` class at the same time, the
+behavior is undefined.
 
 If the flag is true, :class:`catch_warnings` will not modify global
 attributes and will instead use a :class:`~contextvars.ContextVar` to
@@ -655,16 +659,16 @@ thread-safe.
 The *record* parameter of the context handler also behaves differently
 depending on the value of the flag.  When *record* is true and the flag is
 false, the context manager works by replacing and then later restoring the
-module's :func:`showwarning` function.  This is not thread-safe.
+module's :func:`showwarning` function.  That is not concurrent-safe.
 
 When *record* is true and the flag is false, the :func:`showwarning` function
 is not replaced.  The recording status is instead indicated by an internal
 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.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.
+The :data:`~sys.flags.context_aware_warnings` flag can be set the :option:`-X
+context_aware_warnings<-X>` command-line option or by the
+:envvar:`PYTHON_CONTEXT_AWARE_WARNINGS` environment variable.
 
     .. note::
 
@@ -681,6 +685,6 @@ thread_safe_warnings<-X>` command-line option or by the
 
 .. versionchanged:: 3.14
 
-   Added the :data:`sys.flags.thread_safe_warnings` flag and the use of a
+   Added the :data:`sys.flags.context_aware_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,11 +637,11 @@ Miscellaneous options
 
      .. versionadded:: 3.14
 
-   * :samp:`-X thread_safe_warnings={0,1}` causes the
+   * :samp:`-X context_aware_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`.
+     and to ``0`` otherwise.  See also :envvar:`PYTHON_CONTEXT_AWARE_WARNINGS`.
 
      .. versionadded:: 3.14
 
@@ -1248,13 +1248,13 @@ conflict.
 
    .. versionadded:: 3.14
 
-.. envvar:: PYTHON_THREAD_SAFE_WARNINGS
+.. envvar:: PYTHON_CONTEXT_AWARE_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>`.
+   context_aware_warnings<-X>`.
 
    .. versionadded:: 3.14
 

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

diff --git a/Lib/_py_warnings.py b/Lib/_py_warnings.py
@@ -46,7 +46,7 @@ def _set_module(module):
 # 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.thread_safe_warnings
+_use_context = sys.flags.context_aware_warnings
 
 
 class _Context:

diff --git a/Lib/test/test_capi/test_config.py b/Lib/test/test_capi/test_config.py
@@ -56,7 +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),
+            ("context_aware_warnings", int, None),
             ("import_time", bool, None),
             ("inspect", bool, None),
             ("install_signal_handlers", bool, None),
@@ -172,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", "thread_inherit_context" and "thread_safe_warnings" are tested below
+            # "gil", "thread_inherit_context" and "context_aware_warnings" are tested below
         ):
             with self.subTest(flag=flag, name=name, negate=negate):
                 value = config_get(name)
@@ -193,7 +193,7 @@ def test_config_get_sys_flags(self):
         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)
+        self.assertEqual(sys.flags.context_aware_warnings, expected_safe_warnings)
 
     def test_config_get_non_existent(self):
         # Test PyConfig_Get() on non-existent option name

diff --git a/Lib/test/test_embed.py b/Lib/test/test_embed.py
@@ -61,7 +61,7 @@
                            f'{VERSION_MINOR}{ABI_THREAD}/lib-dynload')
 
 DEFAULT_THREAD_INHERIT_CONTEXT = 1 if support.Py_GIL_DISABLED else 0
-DEFAULT_THREAD_SAFE_WARNINGS = 1 if support.Py_GIL_DISABLED else 0
+DEFAULT_CONTEXT_AWARE_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.
@@ -589,7 +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,
+        'context_aware_warnings': DEFAULT_CONTEXT_AWARE_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
@@ -1846,7 +1846,7 @@ def test_pythontypes(self):
         # XXX
         # sys.flags
         # FIXME: The +3 is for the 'gil', 'thread_inherit_context' and
-        # 'thread_safe_warnings' flags and will not be necessary once
+        # 'context_aware_warnings' flags and will not be necessary once
         # gh-122575 is fixed
         check(sys.flags, vsize('') + self.P * (3 + len(sys.flags)))
 

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.thread_safe_warnings`
+the warning filtering state if the :data:`sys.flags.context_aware_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.
+the :option:`-X context_aware_warnings <-X>` command-line option or by the
+:envvar:`PYTHON_CONTEXT_AWARE_WARNINGS` environment variable.
@@ -142,7 +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(context_aware_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
@@ -330,12 +330,11 @@ 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 context_aware_warnings=[0|1]: if true (1) then the warnings module will\n\
+         use a context variables; if false (0) then the warnings module will\n\
+         use module globals, which is not concurrent-safe; set to true for\n\
+         free-threaded builds and false otherwise; also\n\
+         PYTHON_CONTEXT_AWARE_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\
@@ -425,8 +424,8 @@ static const char usage_envvars[] =
 #endif
 "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"
+"PYTHON_CONTEXT_AWARE_WARNINGS: if true (1), enable thread-safe warnings module\n"
+"                   behaviour (-X context_aware_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"
@@ -903,7 +902,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);
+    assert(config->context_aware_warnings >= 0);
 #ifdef __APPLE__
     assert(config->use_system_logger >= 0);
 #endif
@@ -1011,10 +1010,10 @@ _PyConfig_InitCompatConfig(PyConfig *config)
     config->cpu_count = -1;
 #ifdef Py_GIL_DISABLED
     config->thread_inherit_context = 1;
-    config->thread_safe_warnings = 1;
+    config->context_aware_warnings = 1;
 #else
     config->thread_inherit_context = 0;
-    config->thread_safe_warnings = 0;
+    config->context_aware_warnings = 0;
 #endif
 #ifdef __APPLE__
     config->use_system_logger = 0;
@@ -1050,10 +1049,10 @@ config_init_defaults(PyConfig *config)
 #endif
 #ifdef Py_GIL_DISABLED
     config->thread_inherit_context = 1;
-    config->thread_safe_warnings = 1;
+    config->context_aware_warnings = 1;
 #else
     config->thread_inherit_context = 0;
-    config->thread_safe_warnings = 0;
+    config->context_aware_warnings = 0;
 #endif
 #ifdef __APPLE__
     config->use_system_logger = 0;
@@ -1950,27 +1949,27 @@ config_init_thread_inherit_context(PyConfig *config)
 }
 
 static PyStatus
-config_init_thread_safe_warnings(PyConfig *config)
+config_init_context_aware_warnings(PyConfig *config)
 {
-    const char *env = config_get_env(config, "PYTHON_THREAD_SAFE_WARNINGS");
+    const char *env = config_get_env(config, "PYTHON_CONTEXT_AWARE_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");
+                "PYTHON_CONTEXT_AWARE_WARNINGS=N: N is missing or invalid");
         }
-        config->thread_safe_warnings = enabled;
+        config->context_aware_warnings = enabled;
     }
 
-    const wchar_t *xoption = config_get_xoption(config, L"thread_safe_warnings");
+    const wchar_t *xoption = config_get_xoption(config, L"context_aware_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");
+                "-X context_aware_warnings=n: n is missing or invalid");
         }
-        config->thread_safe_warnings = enabled;
+        config->context_aware_warnings = enabled;
     }
     return _PyStatus_OK();
 }
@@ -2259,7 +2258,7 @@ config_read_complex_options(PyConfig *config)
         return status;
     }
 
-    status = config_init_thread_safe_warnings(config);
+    status = config_init_context_aware_warnings(config);
     if (_PyStatus_EXCEPTION(status)) {
         return status;
     }

@@ -3142,7 +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"},
+    {"context_aware_warnings",    "-X context_aware_warnings"},
     {0}
 };
 
@@ -3247,7 +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);
+    SetFlag(config->context_aware_warnings);
 #undef SetFlagObj
 #undef SetFlag
     return 0;