Issue #27319: Methods selection_set(), selection_add(), selection_remove()

and selection_toggle() of ttk.TreeView now allow to pass multiple items as
multiple arguments instead of passing them as a tuple.  Deprecated
undocumented ability of calling the selection() method with arguments.

2 files changed, 85 insertions, 20 deletions

diff --git a/Lib/tkinter/test/test_ttk/test_widgets.py b/Lib/tkinter/test/test_ttk/test_widgets.py
index 8bd22d03e5..26766a8a1f 100644
--- a/Lib/tkinter/test/test_ttk/test_widgets.py
+++ b/Lib/tkinter/test/test_ttk/test_widgets.py
@@ -1487,6 +1487,7 @@ class TreeviewTest(AbstractWidgetTest, unittest.TestCase):
 
 
     def test_selection(self):
+        self.assertRaises(TypeError, self.tv.selection, 'spam')
         # item 'none' doesn't exist
         self.assertRaises(tkinter.TclError, self.tv.selection_set, 'none')
         self.assertRaises(tkinter.TclError, self.tv.selection_add, 'none')
@@ -1500,25 +1501,31 @@ class TreeviewTest(AbstractWidgetTest, unittest.TestCase):
         c3 = self.tv.insert(item1, 'end')
         self.assertEqual(self.tv.selection(), ())
 
-        self.tv.selection_set((c1, item2))
+        self.tv.selection_set(c1, item2)
         self.assertEqual(self.tv.selection(), (c1, item2))
         self.tv.selection_set(c2)
         self.assertEqual(self.tv.selection(), (c2,))
 
-        self.tv.selection_add((c1, item2))
+        self.tv.selection_add(c1, item2)
         self.assertEqual(self.tv.selection(), (c1, c2, item2))
         self.tv.selection_add(item1)
         self.assertEqual(self.tv.selection(), (item1, c1, c2, item2))
+        self.tv.selection_add()
+        self.assertEqual(self.tv.selection(), (item1, c1, c2, item2))
 
-        self.tv.selection_remove((item1, c3))
+        self.tv.selection_remove(item1, c3)
         self.assertEqual(self.tv.selection(), (c1, c2, item2))
         self.tv.selection_remove(c2)
         self.assertEqual(self.tv.selection(), (c1, item2))
+        self.tv.selection_remove()
+        self.assertEqual(self.tv.selection(), (c1, item2))
 
-        self.tv.selection_toggle((c1, c3))
+        self.tv.selection_toggle(c1, c3)
         self.assertEqual(self.tv.selection(), (c3, item2))
         self.tv.selection_toggle(item2)
         self.assertEqual(self.tv.selection(), (c3,))
+        self.tv.selection_toggle()
+        self.assertEqual(self.tv.selection(), (c3,))
 
         self.tv.insert('', 'end', id='with spaces')
         self.tv.selection_set('with spaces')
@@ -1536,6 +1543,40 @@ class TreeviewTest(AbstractWidgetTest, unittest.TestCase):
         self.tv.selection_set(b'bytes\xe2\x82\xac')
         self.assertEqual(self.tv.selection(), ('bytes\xe2\x82\xac',))
 
+        self.tv.selection_set()
+        self.assertEqual(self.tv.selection(), ())
+
+        # Old interface
+        self.tv.selection_set((c1, item2))
+        self.assertEqual(self.tv.selection(), (c1, item2))
+        self.tv.selection_add((c1, item1))
+        self.assertEqual(self.tv.selection(), (item1, c1, item2))
+        self.tv.selection_remove((item1, c3))
+        self.assertEqual(self.tv.selection(), (c1, item2))
+        self.tv.selection_toggle((c1, c3))
+        self.assertEqual(self.tv.selection(), (c3, item2))
+
+        if sys.version_info >= (3, 7):
+            import warnings
+            warnings.warn(
+                'Deprecated API of Treeview.selection() should be removed')
+        self.tv.selection_set()
+        self.assertEqual(self.tv.selection(), ())
+        with self.assertWarns(DeprecationWarning):
+            self.tv.selection('set', (c1, item2))
+        self.assertEqual(self.tv.selection(), (c1, item2))
+        with self.assertWarns(DeprecationWarning):
+            self.tv.selection('add', (c1, item1))
+        self.assertEqual(self.tv.selection(), (item1, c1, item2))
+        with self.assertWarns(DeprecationWarning):
+            self.tv.selection('remove', (item1, c3))
+        self.assertEqual(self.tv.selection(), (c1, item2))
+        with self.assertWarns(DeprecationWarning):
+            self.tv.selection('toggle', (c1, c3))
+        self.assertEqual(self.tv.selection(), (c3, item2))
+        with self.assertWarns(DeprecationWarning):
+            selection = self.tv.selection(None)
+        self.assertEqual(selection, (c3, item2))
 
     def test_set(self):
         self.tv['columns'] = ['A', 'B']
diff --git a/Lib/tkinter/ttk.py b/Lib/tkinter/ttk.py
index 7b71e77ad8..71ac2a7d10 100644
--- a/Lib/tkinter/ttk.py
+++ b/Lib/tkinter/ttk.py
@@ -28,6 +28,8 @@ __all__ = ["Button", "Checkbutton", "Combobox", "Entry", "Frame", "Label",
 import tkinter
 from tkinter import _flatten, _join, _stringify, _splitdict
 
+_sentinel = object()
+
 # Verify if Tk is new enough to not need the Tile package
 _REQUIRE_TILE = True if tkinter.TkVersion < 8.5 else False
 
@@ -1394,31 +1396,53 @@ class Treeview(Widget, tkinter.XView, tkinter.YView):
         self.tk.call(self._w, "see", item)
 
 
-    def selection(self, selop=None, items=None):
-        """If selop is not specified, returns selected items."""
-        if isinstance(items, (str, bytes)):
-            items = (items,)
+    def selection(self, selop=_sentinel, items=None):
+        """Returns the tuple of selected items."""
+        if selop is _sentinel:
+            selop = None
+        elif selop is None:
+            import warnings
+            warnings.warn(
+                "The selop=None argument of selection() is deprecated "
+                "and will be removed in Python 3.7",
+                DeprecationWarning, 3)
+        elif selop in ('set', 'add', 'remove', 'toggle'):
+            import warnings
+            warnings.warn(
+                "The selop argument of selection() is deprecated "
+                "and will be removed in Python 3.7, "
+                "use selection_%s() instead" % (selop,),
+                DeprecationWarning, 3)
+        else:
+            raise TypeError('Unsupported operation')
         return self.tk.splitlist(self.tk.call(self._w, "selection", selop, items))
 
 
-    def selection_set(self, items):
-        """items becomes the new selection."""
-        self.selection("set", items)
+    def _selection(self, selop, items):
+        if len(items) == 1 and isinstance(items[0], (tuple, list)):
+            items = items[0]
+
+        self.tk.call(self._w, "selection", selop, items)
+
+
+    def selection_set(self, *items):
+        """The specified items becomes the new selection."""
+        self._selection("set", items)
 
 
-    def selection_add(self, items):
-        """Add items to the selection."""
-        self.selection("add", items)
+    def selection_add(self, *items):
+        """Add all of the specified items to the selection."""
+        self._selection("add", items)
 
 
-    def selection_remove(self, items):
-        """Remove items from the selection."""
-        self.selection("remove", items)
+    def selection_remove(self, *items):
+        """Remove all of the specified items from the selection."""
+        self._selection("remove", items)
 
 
-    def selection_toggle(self, items):
-        """Toggle the selection state of each item in items."""
-        self.selection("toggle", items)
+    def selection_toggle(self, *items):
+        """Toggle the selection state of each specified item."""
+        self._selection("toggle", items)
 
 
     def set(self, item, column=None, value=None):