gh-128384: Use a context variable for warnings.catch_warnings

Doc/library/sys.rst

@@ -535,7 +535,8 @@ always available. Unless explicitly noted otherwise, all variables are read-only
 .. data:: flags
 
    The :term:`named tuple` *flags* exposes the status of command line
-   flags. The attributes are read only.
+   flags.  Flags should only be accessed only by name and not by index.  The
+   attributes are read only.
 
    .. list-table::
 
@@ -594,6 +595,18 @@ always available. Unless explicitly noted otherwise, all variables are read-only
       * - .. attribute:: flags.warn_default_encoding
         - :option:`-X warn_default_encoding <-X>`
 
+      * - .. attribute:: flags.gil
+        - :option:`-X gil <-X>` and :envvar:`PYTHON_GIL`
+
+      * - .. attribute:: flags.thread_inherit_context
+        - :option:`-X thread_inherit_context <-X>` and
+          :envvar:`PYTHON_THREAD_INHERIT_CONTEXT`
+
+      * - .. attribute:: flags.thread_safe_warnings
+        - :option:`-X thread_inherit_context <-X>` and
+          :envvar:`PYTHON_THREAD_SAFE_WARNINGS`
+
+
    .. versionchanged:: 3.2
       Added ``quiet`` attribute for the new :option:`-q` flag.
 
@@ -620,6 +633,15 @@ always available. Unless explicitly noted otherwise, all variables are read-only
    .. versionchanged:: 3.11
       Added the ``int_max_str_digits`` attribute.
 
+   .. versionchanged:: 3.13
+      Added the ``gil`` attribute.
+
+   .. versionchanged:: 3.14
+      Added the ``thread_inherit_context`` attribute.
+
+   .. versionchanged:: 3.14
+      Added the ``thread_safe_warnings`` attribute.
+
 
 .. data:: float_info
 

Doc/library/threading.rst

@@ -334,7 +334,7 @@ since it is impossible to detect the termination of alien threads.
 
 
 .. class:: Thread(group=None, target=None, name=None, args=(), kwargs={}, *, \
-                  daemon=None)
+                  daemon=None, context=None)
 
    This constructor should always be called with keyword arguments.  Arguments
    are:
@@ -359,6 +359,16 @@ since it is impossible to detect the termination of alien threads.
    If ``None`` (the default), the daemonic property is inherited from the
    current thread.
 
+   *context* is the :class:`~contextvars.Context` value to use when starting
+   the thread.  The default value is ``None`` which indicates that the
+   :data:`sys.flags.thread_inherit_context` flag controls the behaviour.  If
+   the flag is true, threads will start with a copy of the context of the
+   caller of :meth:`~Thread.start`.  If false, they will start with an empty
+   context.  To explicitly start with an empty context, pass a new instance of
+   :class:`~contextvars.Context()`.  To explicitly start with a copy of the
+   current context, pass the value from :func:`~contextvars.copy_context`. The
+   flag defaults true on free-threaded builds and false otherwise.
+
    If the subclass overrides the constructor, it must make sure to invoke the
    base class constructor (``Thread.__init__()``) before doing anything else to
    the thread.
@@ -369,6 +379,9 @@ since it is impossible to detect the termination of alien threads.
    .. versionchanged:: 3.10
       Use the *target* name if *name* argument is omitted.
 
+   .. versionchanged:: 3.14
+      Added the *context* parameter.
+
    .. method:: start()
 
       Start the thread's activity.

Doc/library/warnings.rst

@@ -324,11 +324,13 @@ the warning using the :class:`catch_warnings` context manager::
 While within the context manager all warnings will simply be ignored. This
 allows you to use known-deprecated code without having to see the warning while
 not suppressing the warning for other code that might not be aware of its use
-of deprecated code.  Note: this can only be guaranteed in a single-threaded
-application. If two or more threads use the :class:`catch_warnings` context
-manager at the same time, the behavior is undefined.
+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.
 
 .. _warning-testing:
 
@@ -364,10 +366,13 @@ the warning has been cleared.
 Once the context manager exits, the warnings filter is restored to its state
 when the context was entered. This prevents tests from changing the warnings
 filter in unexpected ways between tests and leading to indeterminate test
-results. The :func:`showwarning` function in the module is also restored to
-its original value.  Note: this can only be guaranteed in a single-threaded
-application. If two or more threads use the :class:`catch_warnings` context
-manager at the same time, the behavior is undefined.
+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.
 
 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
@@ -615,12 +620,67 @@ Available Context Managers
 
     .. note::
 
-        The :class:`catch_warnings` manager works by replacing and
-        then later restoring the module's
-        :func:`showwarning` function and internal list of filter
-        specifications.  This means the context manager is modifying
-        global state and therefore is not thread-safe.
+        See :ref:`warning-thread-safe` for details on the thread-safety of the
+        :class:`catch_warnings` context manager when used in multi-threaded
+        programs.
+
 
     .. versionchanged:: 3.11
 
         Added the *action*, *category*, *lineno*, and *append* parameters.
+
+
+.. _warning-thread-safe:
+
+Thread-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.
+
+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 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`
+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.
+
+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.
+
+    .. note::
+
+        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.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.

Doc/using/cmdline.rst

@@ -628,6 +628,23 @@ Miscellaneous options
 
      .. versionadded:: 3.13
 
+   * :samp:`-X thread_inherit_context={0,1}` causes :class:`~threading.Thread`
+     to, by default, use a copy of context of of the caller of
+     ``Thread.start()`` when starting.  Otherwise, threads will start
+     with an empty context.  If unset, the value of this option defaults
+     to ``1`` on free-threaded builds and to ``0`` otherwise.  See also
+     :envvar:`PYTHON_THREAD_INHERIT_CONTEXT`.
+
+     .. 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.
 
@@ -1221,6 +1238,26 @@ conflict.
 
    .. versionadded:: 3.13
 
+.. envvar:: PYTHON_THREAD_INHERIT_CONTEXT
+
+   If this variable is set to ``1`` then :class:`~threading.Thread` will,
+   by default, use a copy of context of of the caller of ``Thread.start()``
+   when starting.  Otherwise, new threads will start with an empty context.
+   If unset, this variable defaults to ``1`` on free-threaded builds and to
+   ``0`` otherwise.  See also :option:`-X thread_inherit_context<-X>`.
+
+   .. 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
 ~~~~~~~~~~~~~~~~~~~~
 

Include/cpython/initconfig.h

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

Include/internal/pycore_global_strings.h

@@ -265,6 +265,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(_type_)
         STRUCT_FOR_ID(_uninitialized_submodules)
         STRUCT_FOR_ID(_warn_unawaited_coroutine)
+        STRUCT_FOR_ID(_warnings_context)
         STRUCT_FOR_ID(_xoptions)
         STRUCT_FOR_ID(abs_tol)
         STRUCT_FOR_ID(access)

Lib/test/support/__init__.py

@@ -2359,8 +2359,9 @@ def clear_ignored_deprecations(*tokens: object) -> None:
         raise ValueError("Provide token or tokens returned by ignore_deprecations_from")
 
     new_filters = []
+    old_filters = warnings._get_filters()
     endswith = tuple(rf"(?#support{id(token)})" for token in tokens)
-    for action, message, category, module, lineno in warnings.filters:
+    for action, message, category, module, lineno in old_filters:
         if action == "ignore" and category is DeprecationWarning:
             if isinstance(message, re.Pattern):
                 msg = message.pattern
@@ -2369,8 +2370,8 @@ def clear_ignored_deprecations(*tokens: object) -> None:
             if msg.endswith(endswith):
                 continue
         new_filters.append((action, message, category, module, lineno))
-    if warnings.filters != new_filters:
-        warnings.filters[:] = new_filters
+    if old_filters != new_filters:
+        old_filters[:] = new_filters
         warnings._filters_mutated()
 
 

Lib/test/test_capi/test_config.py

@@ -55,6 +55,8 @@ def test_config_get(self):
             ("filesystem_errors", str, None),
             ("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),
@@ -98,7 +100,7 @@ def test_config_get(self):
         ]
         if support.Py_DEBUG:
             options.append(("run_presite", str | None, None))
-        if sysconfig.get_config_var('Py_GIL_DISABLED'):
+        if support.Py_GIL_DISABLED:
             options.append(("enable_gil", int, None))
             options.append(("tlbc_enabled", int, None))
         if support.MS_WINDOWS:
@@ -170,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" is 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)
@@ -182,11 +184,17 @@ def test_config_get_sys_flags(self):
                          config_get('use_hash_seed') == 0
                          or config_get('hash_seed') != 0)
 
-        if sysconfig.get_config_var('Py_GIL_DISABLED'):
+        if support.Py_GIL_DISABLED:
             value = config_get('enable_gil')
             expected = (value if value != -1 else None)
             self.assertEqual(sys.flags.gil, expected)
 
+        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