gh-50409: Modernize tkinter.PanedWindow.paneconfigure() (GH-152399)

Rename the first parameter of paneconfigure() (and its paneconfig alias)
from 'tagOrId' to 'child', for consistency with add(), remove() and
panecget() -- PanedWindow panes are child widgets, not tagged items.  The
old 'tagOrId' keyword still works but raises DeprecationWarning.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst
index 6d62385f40bf483dc3a1295572142b6cf7e9c7b7..fe54e831afbcd49d14dce7cd2cfac88762dc717c 100644 (file)
--- a/Doc/library/tkinter.rst
+++ b/Doc/library/tkinter.rst
@@ -4938,13 +4938,13 @@ Widget classes
       containing *child*.
       *option* may be any value allowed by :meth:`paneconfigure`.
 
-   .. method:: paneconfig(tagOrId, cnf=None, **kw)
+   .. method:: paneconfig(child, cnf=None, **kw)
       :no-typesetting:
 
-   .. method:: paneconfigure(tagOrId, cnf=None, **kw)
+   .. method:: paneconfigure(child, cnf=None, **kw)
 
       Query or modify the management options of the pane containing the widget
-      *tagOrId*.
+      *child*.
       With no options, it returns a dictionary describing all of the available
       options for the pane; given a single option name as a string, it returns
       a description of that one option; otherwise it sets the given options.
@@ -4959,6 +4959,10 @@ Widget classes
       ``'always'``, ``'first'``, ``'last'``, ``'middle'`` or ``'never'``).
       :meth:`paneconfig` is an alias of :meth:`!paneconfigure`.
 
+      .. deprecated-removed:: next 3.18
+         The first parameter was renamed from *tagOrId* to *child*.
+         The old name is still accepted as a keyword argument.
+
    .. method:: identify(x, y)
 
       Identify the panedwindow component underneath the point given by *x* and

diff --git a/Lib/test/test_tkinter/test_widgets.py b/Lib/test/test_tkinter/test_widgets.py
index 970eddc955f3aaea3c7595b53456e857181e1f1b..98c78895e8493295587a85a3473b09d152da2656 100644 (file)
--- a/Lib/test/test_tkinter/test_widgets.py
+++ b/Lib/test/test_tkinter/test_widgets.py
@@ -2404,6 +2404,27 @@ class PanedWindowTest(AbstractWidgetTest, unittest.TestCase):
         self.check_paneconfigure_bad(p, b, 'width',
                 EXPECTED_SCREEN_DISTANCE_OR_EMPTY_ERRMSG.format('badValue'))
 
+    def test_paneconfigure_child(self):
+        p, b, c = self.create2()
+        # The child pane is the first argument, positionally or by keyword.
+        p.paneconfigure(b, minsize=40)
+        self.assertEqual(p.panecget(b, 'minsize'), 40)
+        p.paneconfigure(child=b, minsize=50)
+        self.assertEqual(p.panecget(b, 'minsize'), 50)
+        self.assertIsInstance(p.paneconfigure(b), dict)
+        self.assertEqual(p.paneconfigure(b, 'minsize')[4], 50)
+        # Omitting the child is an error.
+        self.assertRaises(TypeError, p.paneconfigure)
+
+    def test_paneconfigure_tagOrId_deprecated(self):
+        p, b, c = self.create2()
+        # 'tagOrId' is a deprecated alias of 'child'.
+        with self.assertWarns(DeprecationWarning):
+            p.paneconfigure(tagOrId=b, minsize=40)
+        self.assertEqual(p.panecget(b, 'minsize'), 40)
+        # Giving both 'child' and 'tagOrId' is an error.
+        self.assertRaises(TypeError, p.paneconfigure, b, tagOrId=c)
+
 
 @add_configure_tests(StandardOptionsTests)
 class MenuTest(AbstractWidgetTest, unittest.TestCase):

diff --git a/Lib/tkinter/__init__.py b/Lib/tkinter/__init__.py
index 6c8eef02478c774f776e66d950e69f51a5cd53c0..afc68726f7c8d5d23cd70a8d24609ca28d007cb3 100644 (file)
--- a/Lib/tkinter/__init__.py
+++ b/Lib/tkinter/__init__.py
@@ -5345,7 +5345,7 @@ class PanedWindow(Widget):
         return self.tk.call(
             (self._w, 'panecget') + (child, '-'+option))
 
-    def paneconfigure(self, tagOrId, cnf=None, **kw):
+    def paneconfigure(self, child=None, cnf=None, **kw):
         """Query or modify the configuration options for a child window.
 
         Similar to configure() except that it applies to the specified
@@ -5407,12 +5407,26 @@ class PanedWindow(Widget):
             Tk_GetPixels.
 
         """
+        if 'tagOrId' in kw:
+            if child is not None:
+                raise TypeError("paneconfigure() got values for both 'child' "
+                                "and its deprecated alias 'tagOrId'")
+            import warnings
+            warnings.warn(
+                    "The 'tagOrId' parameter of PanedWindow.paneconfigure() "
+                    "is deprecated and will be removed in Python 3.18; "
+                    "use 'child' instead.",
+                    DeprecationWarning, stacklevel=2)
+            child = kw.pop('tagOrId')
+        if child is None:
+            raise TypeError("paneconfigure() missing 1 required positional "
+                            "argument: 'child'")
         if cnf is None and not kw:
-            return self._getconfigure(self._w, 'paneconfigure', tagOrId)
+            return self._getconfigure(self._w, 'paneconfigure', child)
         if isinstance(cnf, str) and not kw:
             return self._getconfigure1(
-                self._w, 'paneconfigure', tagOrId, '-'+cnf)
-        self.tk.call((self._w, 'paneconfigure', tagOrId) +
+                self._w, 'paneconfigure', child, '-'+cnf)
+        self.tk.call((self._w, 'paneconfigure', child) +
                  self._options(cnf, kw))
 
     paneconfig = paneconfigure

diff --git a/Misc/NEWS.d/next/Library/2026-06-27-11-32-37.gh-issue-50409.Pw3Kq9.rst b/Misc/NEWS.d/next/Library/2026-06-27-11-32-37.gh-issue-50409.Pw3Kq9.rst
new file mode 100644 (file)
index 0000000..479a2a3
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2026-06-27-11-32-37.gh-issue-50409.Pw3Kq9.rst
@@ -0,0 +1,4 @@
+Deprecate the *tagOrId* parameter of
+:meth:`!tkinter.PanedWindow.paneconfigure` (and its :meth:`!paneconfig`
+alias) in favor of *child*, for consistency with the other pane methods;
+it will be removed in Python 3.18.