From e62d698830edb1d9d5e193f3e1de44f7d845af20 Mon Sep 17 00:00:00 2001
From: Serhiy Storchaka <storchaka@gmail.com>
Date: Tue, 23 Jun 2026 17:21:01 +0300
Subject: [PATCH] gh-127802: Schedule removal of legacy tkinter variable trace
 methods in 3.17

The tkinter.Variable methods trace_variable(), trace(), trace_vdelete()
and trace_vinfo(), deprecated since Python 3.14, are now scheduled for
removal in Python 3.17.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 Doc/deprecations/pending-removal-in-3.17.rst  | 10 ++++++++
 Lib/tkinter/__init__.py                       | 24 ++++++++++++-------
 ...-06-23-17-14-04.gh-issue-127802.nGSxo6.rst |  3 +++
 3 files changed, 28 insertions(+), 9 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Library/2026-06-23-17-14-04.gh-issue-127802.nGSxo6.rst

diff --git a/Doc/deprecations/pending-removal-in-3.17.rst b/Doc/deprecations/pending-removal-in-3.17.rst
index 8ee7f335cc9514..d6e4e81afbbd63 100644
--- a/Doc/deprecations/pending-removal-in-3.17.rst
+++ b/Doc/deprecations/pending-removal-in-3.17.rst
@@ -68,3 +68,13 @@ Pending removal in Python 3.17
 
     See :pep:`PEP 688 <688#current-options>` for more details.
     (Contributed by Shantanu Jain in :gh:`91896`.)
+
+* :mod:`tkinter`:
+
+  - The :class:`!tkinter.Variable` methods :meth:`!trace_variable`,
+    :meth:`!trace` (an alias of :meth:`!trace_variable`),
+    :meth:`!trace_vdelete` and :meth:`!trace_vinfo`, deprecated since
+    Python 3.14, are scheduled for removal in Python 3.17.
+    Use :meth:`!trace_add`, :meth:`!trace_remove` and :meth:`!trace_info`
+    instead.
+    (Contributed by Serhiy Storchaka in :gh:`120220`.)
diff --git a/Lib/tkinter/__init__.py b/Lib/tkinter/__init__.py
index 122f4da25de5a2..2e1230dc449f96 100644
--- a/Lib/tkinter/__init__.py
+++ b/Lib/tkinter/__init__.py
@@ -505,12 +505,14 @@ def trace_variable(self, mode, callback):
         Return the name of the callback.
 
         This deprecated method wraps a deprecated Tcl method removed
-        in Tcl 9.0.  Use trace_add() instead.
+        in Tcl 9.0 and will be removed in Python 3.17.  Use trace_add()
+        instead.
         """
         import warnings
         warnings.warn(
-                "trace_variable() is deprecated and not supported with Tcl 9; "
-                "use trace_add() instead.",
+                "trace_variable() is deprecated and will be removed in Python "
+                "3.17; use trace_add() instead.  It is not supported with "
+                "Tcl 9.",
                 DeprecationWarning, stacklevel=2)
         cbname = self._register(callback)
         self._tk.call("trace", "variable", self._name, mode, cbname)
@@ -525,12 +527,14 @@ def trace_vdelete(self, mode, cbname):
         CBNAME is the name of the callback returned from trace_variable or trace.
 
         This deprecated method wraps a deprecated Tcl method removed
-        in Tcl 9.0.  Use trace_remove() instead.
+        in Tcl 9.0 and will be removed in Python 3.17.  Use trace_remove()
+        instead.
         """
         import warnings
         warnings.warn(
-                "trace_vdelete() is deprecated and not supported with Tcl 9; "
-                "use trace_remove() instead.",
+                "trace_vdelete() is deprecated and will be removed in Python "
+                "3.17; use trace_remove() instead.  It is not supported with "
+                "Tcl 9.",
                 DeprecationWarning, stacklevel=2)
         self._tk.call("trace", "vdelete", self._name, mode, cbname)
         cbname = self._tk.splitlist(cbname)[0]
@@ -548,12 +552,14 @@ def trace_vinfo(self):
         """Return all trace callback information.
 
         This deprecated method wraps a deprecated Tcl method removed
-        in Tcl 9.0.  Use trace_info() instead.
+        in Tcl 9.0 and will be removed in Python 3.17.  Use trace_info()
+        instead.
         """
         import warnings
         warnings.warn(
-                "trace_vinfo() is deprecated and not supported with Tcl 9; "
-                "use trace_info() instead.",
+                "trace_vinfo() is deprecated and will be removed in Python "
+                "3.17; use trace_info() instead.  It is not supported with "
+                "Tcl 9.",
                 DeprecationWarning, stacklevel=2)
         return [self._tk.splitlist(x) for x in self._tk.splitlist(
             self._tk.call("trace", "vinfo", self._name))]
diff --git a/Misc/NEWS.d/next/Library/2026-06-23-17-14-04.gh-issue-127802.nGSxo6.rst b/Misc/NEWS.d/next/Library/2026-06-23-17-14-04.gh-issue-127802.nGSxo6.rst
new file mode 100644
index 00000000000000..9484c9dbd23b2f
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2026-06-23-17-14-04.gh-issue-127802.nGSxo6.rst
@@ -0,0 +1,3 @@
+The deprecated :class:`tkinter.Variable` methods :meth:`!trace_variable`,
+:meth:`!trace`, :meth:`!trace_vdelete` and :meth:`!trace_vinfo` are now
+scheduled for removal in Python 3.17.