[3.14] gh-123193: Document tkinter Variable lifetime (GH-152625) (GH-153099)

A Tk variable wrapper unsets its Tcl variable when garbage collected, so a
reference must be kept while a widget uses it.  Otherwise Tk recreates the Tcl
variable but never unsets it again, leaking it.
(cherry picked from commit 820b6ca22d72482e2e68dd738cc370535c83655e)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst
index d23005ebd8af0554218408fb8f694b4a834e0ced..0b66296641e21107b638d625e1e9aff120df8cdb 100644 (file)
--- a/Doc/library/tkinter.rst
+++ b/Doc/library/tkinter.rst
@@ -658,6 +658,9 @@ method on it, and to change its value you call the :meth:`!set` method.
 If you follow this protocol, the widget will always track the value of the
 variable, with no further intervention on your part.
 
+Keep a reference to the variable for as long as a widget uses it, for example
+by storing it as an attribute (see :class:`Variable`).
+
 For example::
 
    import tkinter as tk
@@ -5658,6 +5661,14 @@ Variable classes
    :class:`StringVar`, :class:`IntVar`, :class:`DoubleVar` or
    :class:`BooleanVar` -- rather than :class:`!Variable` directly.
 
+   .. note::
+
+      When a :class:`!Variable` is garbage collected, its Tcl variable is unset.
+      Keep a reference to it for as long as a widget is linked to it, for example
+      by storing it as an attribute rather than in a local variable.
+      Otherwise Tk recreates the Tcl variable to keep the widget working, but it
+      is never unset again, leaking one Tcl variable per dropped wrapper.
+
    .. versionchanged:: 3.10
       Two variables now compare equal (``==``) only when they have the same
       name, are of the same class, and belong to the same Tcl interpreter.