From 7ce02243ed7e02637ca2bced5c95a66937368541 Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend@python.org>
Date: Tue, 4 Jul 2023 13:11:37 +0200
Subject: [PATCH] gh-106368: Add tests for permutation helpers in Argument
 Clinic

Added new test class PermutationTests()
---
 Lib/test/test_clinic.py | 106 ++++++++++++++++++++++++++++++++++++++++
 Tools/clinic/clinic.py  |   4 +-
 2 files changed, 108 insertions(+), 2 deletions(-)

diff --git a/Lib/test/test_clinic.py b/Lib/test/test_clinic.py
index 03754d0bf123be..544e7323e4f606 100644
--- a/Lib/test/test_clinic.py
+++ b/Lib/test/test_clinic.py
@@ -1586,5 +1586,111 @@ def test_cloned_func_with_converter_exception_message(self):
                 self.assertEqual(func(), name)
 
 
+class PermutationTests(unittest.TestCase):
+    """Test permutation support functions."""
+
+    def test_permute_left_option_groups(self):
+        expected = (
+            (),
+            (3,),
+            (2, 3),
+            (1, 2, 3),
+        )
+        data = list(zip([1, 2, 3]))  # Generate a list of 1-tuples.
+        actual = tuple(clinic.permute_left_option_groups(data))
+        self.assertEqual(actual, expected)
+
+    def test_permute_right_option_groups(self):
+        expected = (
+            (),
+            (1,),
+            (1, 2),
+            (1, 2, 3),
+        )
+        data = list(zip([1, 2, 3]))  # Generate a list of 1-tuples.
+        actual = tuple(clinic.permute_right_option_groups(data))
+        self.assertEqual(actual, expected)
+
+    def test_permute_optional_groups(self):
+        empty = {
+            "left": (), "required": (), "right": (),
+            "expected": ((),),
+        }
+        noleft1 = {
+            "left": (), "required": ("b",), "right": ("c",),
+            "expected": (
+                ("b",),
+                ("b", "c"),
+            ),
+        }
+        noleft2 = {
+            "left": (), "required": ("b", "c",), "right": ("d",),
+            "expected": (
+                ("b", "c"),
+                ("b", "c", "d"),
+            ),
+        }
+        noleft3 = {
+            "left": (), "required": ("b", "c",), "right": ("d", "e"),
+            "expected": (
+                ("b", "c"),
+                ("b", "c", "d"),
+                ("b", "c", "d", "e"),
+            ),
+        }
+        noright1 = {
+            "left": ("a",), "required": ("b",), "right": (),
+            "expected": (
+                ("b",),
+                ("a", "b"),
+            ),
+        }
+        noright2 = {
+            "left": ("a",), "required": ("b", "c"), "right": (),
+            "expected": (
+                ("b", "c"),
+                ("a", "b", "c"),
+            ),
+        }
+        noright3 = {
+            "left": ("a", "b"), "required": ("c",), "right": (),
+            "expected": (
+                ("c",),
+                ("b", "c"),
+                ("a", "b", "c"),
+            ),
+        }
+        leftandright1 = {
+            "left": ("a",), "required": ("b",), "right": ("c",),
+            "expected": (
+                ("b",),
+                ("a", "b"),  # Prefer left.
+                ("a", "b", "c"),
+            ),
+        }
+        leftandright2 = {
+            "left": ("a", "b"), "required": ("c", "d"), "right": ("e", "f"),
+            "expected": (
+                ("c", "d"),
+                ("b", "c", "d"),       # Prefer left.
+                ("a", "b", "c", "d"),  # Prefer left.
+                ("a", "b", "c", "d", "e"),
+                ("a", "b", "c", "d", "e", "f"),
+            ),
+        }
+        dataset = (
+            empty,
+            noleft1, noleft2, noleft3,
+            noright1, noright2, noright3,
+            leftandright1, leftandright2,
+        )
+        for params in dataset:
+            with self.subTest(**params):
+                left, required, right, expected = params.values()
+                permutations = clinic.permute_optional_groups(left, required, right)
+                actual = tuple(permutations)
+                self.assertEqual(actual, expected)
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/Tools/clinic/clinic.py b/Tools/clinic/clinic.py
index a07fcbd8cabf76..c02c82876591f8 100755
--- a/Tools/clinic/clinic.py
+++ b/Tools/clinic/clinic.py
@@ -518,7 +518,7 @@ class PythonLanguage(Language):
 
 def permute_left_option_groups(l):
     """
-    Given [1, 2, 3], should yield:
+    Given [(1,), (2,), (3,)], should yield:
        ()
        (3,)
        (2, 3)
@@ -533,7 +533,7 @@ def permute_left_option_groups(l):
 
 def permute_right_option_groups(l):
     """
-    Given [1, 2, 3], should yield:
+    Given [(1,), (2,), (3,)], should yield:
       ()
       (1,)
       (1, 2)