gh-104050: Annotate Argument Clinic parameter permutation helpers (#106431)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

Tools/clinic/clinic.py

@@ -28,7 +28,12 @@ import sys
 import textwrap
 import traceback
 
-from collections.abc import Callable
+from collections.abc import (
+    Callable,
+    Iterable,
+    Iterator,
+    Sequence,
+)
 from types import FunctionType, NoneType
 from typing import (
     Any,
@@ -516,7 +521,13 @@ class PythonLanguage(Language):
     checksum_line = "#/*[{dsl_name} end generated code: {arguments}]*/"
 
 
-def permute_left_option_groups(l):
+ParamGroup = Iterable["Parameter"]
+ParamTuple = tuple["Parameter", ...]
+
+
+def permute_left_option_groups(
+        l: Sequence[ParamGroup]
+) -> Iterator[ParamTuple]:
     """
     Given [(1,), (2,), (3,)], should yield:
        ()
@@ -525,13 +536,15 @@ def permute_left_option_groups(l):
        (1, 2, 3)
     """
     yield tuple()
-    accumulator = []
+    accumulator: list[Parameter] = []
     for group in reversed(l):
         accumulator = list(group) + accumulator
         yield tuple(accumulator)
 
 
-def permute_right_option_groups(l):
+def permute_right_option_groups(
+        l: Sequence[ParamGroup]
+) -> Iterator[ParamTuple]:
     """
     Given [(1,), (2,), (3,)], should yield:
       ()
@@ -540,13 +553,17 @@ def permute_right_option_groups(l):
       (1, 2, 3)
     """
     yield tuple()
-    accumulator = []
+    accumulator: list[Parameter] = []
     for group in l:
         accumulator.extend(group)
         yield tuple(accumulator)
 
 
-def permute_optional_groups(left, required, right):
+def permute_optional_groups(
+        left: Sequence[ParamGroup],
+        required: ParamGroup,
+        right: Sequence[ParamGroup]
+) -> tuple[ParamTuple, ...]:
     """
     Generator function that computes the set of acceptable
     argument lists for the provided iterables of
@@ -561,7 +578,7 @@ def permute_optional_groups(left, required, right):
         if left:
             raise ValueError("required is empty but left is not")
 
-    accumulator = []
+    accumulator: list[ParamTuple] = []
     counts = set()
     for r in permute_right_option_groups(right):
         for l in permute_left_option_groups(left):