bpo-44584: Deprecate PYTHONTHREADDEBUG env var (GH-27065)

The threading debug (PYTHONTHREADDEBUG environment variable) is
deprecated in Python 3.10 and will be removed in Python 3.12. This
feature requires a debug build of Python.
(cherry picked from commit 4d77691172aae81bdcbb0ea75839d0e896c43781)

Co-authored-by: Victor Stinner <vstinner@python.org>

diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 25e05d413de877edc4aab17d08764bed65d03bc1..f22548facd0f926f0c97b09200e64afaf5abe74f 100644 (file)
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -942,10 +942,12 @@ Debug-mode variables
 
 .. envvar:: PYTHONTHREADDEBUG
 
-   If set, Python will print threading debug info.
+   If set, Python will print threading debug info into stdout.
 
    Need a :ref:`debug build of Python <debug-build>`.
 
+   .. deprecated-removed:: 3.10 3.12
+
 
 .. envvar:: PYTHONDUMPREFS
 

diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index 5af1693e90cacf6d1e7281df06f3222b3f67bb47..d9a90fb63f18ed2a048313a121dd264a18c4fb6f 100644 (file)
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -1687,6 +1687,11 @@ Deprecated
   * NPN features like :meth:`ssl.SSLSocket.selected_npn_protocol` and
     :meth:`ssl.SSLContext.set_npn_protocols` are replaced by ALPN.
 
+* The threading debug (:envvar:`PYTHONTHREADDEBUG` environment variable) is
+  deprecated in Python 3.10 and will be removed in Python 3.12. This feature
+  requires a :ref:`debug build of Python <debug-build>`.
+  (Contributed by Victor Stinner in :issue:`44584`.)
+
 .. _whatsnew310-removed:
 
 Removed

diff --git a/Lib/test/test_threading.py b/Lib/test/test_threading.py
index 23fe2d3f4d32e2ae2043ba12fa8aad7df53648c8..c51de6f4b85537f998565c764a36b532c8438e23 100644 (file)
--- a/Lib/test/test_threading.py
+++ b/Lib/test/test_threading.py
@@ -32,6 +32,9 @@ from test import support
 # on platforms known to behave badly.
 platforms_to_skip = ('netbsd5', 'hp-ux11')
 
+# Is Python built with Py_DEBUG macro defined?
+Py_DEBUG = hasattr(sys, 'gettotalrefcount')
+
 
 def restore_default_excepthook(testcase):
     testcase.addCleanup(setattr, threading, 'excepthook', threading.excepthook)
@@ -915,6 +918,16 @@ class ThreadTests(BaseTestCase):
             threading.Thread(target=noop).start()
             # Thread.join() is not called
 
+    @unittest.skipUnless(Py_DEBUG, 'need debug build (Py_DEBUG)')
+    def test_debug_deprecation(self):
+        # bpo-44584: The PYTHONTHREADDEBUG environment variable is deprecated
+        rc, out, err = assert_python_ok("-Wdefault", "-c", "pass",
+                                        PYTHONTHREADDEBUG="1")
+        msg = (b'DeprecationWarning: The threading debug '
+               b'(PYTHONTHREADDEBUG environment variable) '
+               b'is deprecated and will be removed in Python 3.12')
+        self.assertIn(msg, err)
+
 
 class ThreadJoinOnShutdown(BaseTestCase):
 

diff --git a/Misc/NEWS.d/next/Core and Builtins/2021-07-08-12-18-56.bpo-44584.qKnSqV.rst b/Misc/NEWS.d/next/Core and Builtins/2021-07-08-12-18-56.bpo-44584.qKnSqV.rst
new file mode 100644 (file)
index 0000000..4afb33b
--- /dev/null
+++ b/Misc/NEWS.d/next/Core and Builtins/2021-07-08-12-18-56.bpo-44584.qKnSqV.rst
@@ -0,0 +1,3 @@
+The threading debug (:envvar:`PYTHONTHREADDEBUG` environment variable) is
+deprecated in Python 3.10 and will be removed in Python 3.12. This feature
+requires a debug build of Python. Patch by Victor Stinner.

diff --git a/Misc/python.man b/Misc/python.man
index 10cb807c38a02c64bfc0d3bb4d07cc0828496831..45a49271d4dfe3cd6e88e9bbeebad47a6edd5186 100644 (file)
--- a/Misc/python.man
+++ b/Misc/python.man
@@ -550,6 +550,7 @@ if Python was configured with the
 \fB\--with-pydebug\fP build option.
 .IP PYTHONTHREADDEBUG
 If this environment variable is set, Python will print threading debug info.
+The feature is deprecated in Python 3.10 and will be removed in Python 3.12.
 .IP PYTHONDUMPREFS
 If this environment variable is set, Python will dump objects and reference
 counts still alive after shutting down the interpreter.

diff --git a/Python/pylifecycle.c b/Python/pylifecycle.c
index d31a9c15fd1ec57ff59f9bc5df73099f798cf87b..eeaf20b4617a2095bc6702199e509f5435870a4a 100644 (file)
--- a/Python/pylifecycle.c
+++ b/Python/pylifecycle.c
@@ -1057,6 +1057,8 @@ pyinit_main_reconfigure(PyThreadState *tstate)
 static PyStatus
 init_interp_main(PyThreadState *tstate)
 {
+    extern void _PyThread_debug_deprecation(void);
+
     assert(!_PyErr_Occurred(tstate));
 
     PyStatus status;
@@ -1158,6 +1160,9 @@ init_interp_main(PyThreadState *tstate)
 #endif
     }
 
+    // Warn about PYTHONTHREADDEBUG deprecation
+    _PyThread_debug_deprecation();
+
     assert(!_PyErr_Occurred(tstate));
 
     return _PyStatus_OK();

diff --git a/Python/thread.c b/Python/thread.c
index a10f5728dc0ceb8cc560cf830851da862c680679..dfe28b6bdb680d1a41a8449c0a0bb3b4f22b66fa 100644 (file)
--- a/Python/thread.c
+++ b/Python/thread.c
@@ -75,6 +75,25 @@ PyThread_init_thread(void)
     PyThread__init_thread();
 }
 
+void
+_PyThread_debug_deprecation(void)
+{
+#ifdef Py_DEBUG
+    if (thread_debug) {
+        // Flush previous dprintf() logs
+        fflush(stdout);
+        if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                         "The threading debug (PYTHONTHREADDEBUG environment "
+                         "variable) is deprecated and will be removed "
+                         "in Python 3.12",
+                         0))
+        {
+            _PyErr_WriteUnraisableMsg("at Python startup", NULL);
+        }
+    }
+#endif
+}
+
 #if defined(_POSIX_THREADS)
 #   define PYTHREAD_NAME "pthread"
 #   include "thread_pthread.h"