From 02a872b3850b125588c5bc9df5a7122b5e2e15c8 Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend@python.org>
Date: Mon, 3 Jul 2023 00:14:17 +0200
Subject: [PATCH 1/2] gh-104050: Add more type hints to Argument Clinic
 DSLParser()

Annotate the following method signatures:

- state_dsl_start()
- state_parameter_docstring_start()
- state_parameters_start()

Inverting ignore_line() logic, add type hints (including type guard) to
it, and rename to valid_line().
---
 Tools/clinic/clinic.py | 33 ++++++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 11 deletions(-)

diff --git a/Tools/clinic/clinic.py b/Tools/clinic/clinic.py
index 43b7a9d9ac4aa7..f1a27c76d10c8f 100755
--- a/Tools/clinic/clinic.py
+++ b/Tools/clinic/clinic.py
@@ -29,7 +29,15 @@
 
 from collections.abc import Callable
 from types import FunctionType, NoneType
-from typing import Any, Final, NamedTuple, NoReturn, Literal, overload
+from typing import (
+    Any,
+    Final,
+    Literal,
+    NamedTuple,
+    NoReturn,
+    TypeGuard,
+    overload,
+)
 
 # TODO:
 #
@@ -4471,17 +4479,20 @@ def parse(self, block: Block) -> None:
             block.output = self.saved_output
 
     @staticmethod
-    def ignore_line(line):
+    def valid_line(line: str | None) -> TypeGuard[str]:
+        if line is None:
+            return False
+
         # ignore comment-only lines
         if line.lstrip().startswith('#'):
-            return True
+            return False
 
         # Ignore empty lines too
         # (but not in docstring sections!)
         if not line.strip():
-            return True
+            return False
 
-        return False
+        return True
 
     @staticmethod
     def calculate_indent(line: str) -> int:
@@ -4497,9 +4508,9 @@ def next(
         if line is not None:
             self.state(line)
 
-    def state_dsl_start(self, line):
+    def state_dsl_start(self, line: str | None):
         # self.block = self.ClinicOutputBlock(self)
-        if self.ignore_line(line):
+        if not self.valid_line(line):
             return
 
         # is it a directive?
@@ -4716,8 +4727,8 @@ def state_modulename_name(self, line):
     ps_start, ps_left_square_before, ps_group_before, ps_required, \
     ps_optional, ps_group_after, ps_right_square_after = range(7)
 
-    def state_parameters_start(self, line):
-        if self.ignore_line(line):
+    def state_parameters_start(self, line: str) -> None:
+        if not self.valid_line(line):
             return
 
         # if this line is not indented, we have no parameters
@@ -4742,7 +4753,7 @@ def state_parameter(self, line):
             line = self.parameter_continuation + ' ' + line.lstrip()
             self.parameter_continuation = ''
 
-        if self.ignore_line(line):
+        if not self.valid_line(line):
             return
 
         assert self.indent.depth == 2
@@ -5075,7 +5086,7 @@ def parse_special_symbol(self, symbol):
                     fail("Function " + self.function.name + " mixes keyword-only and positional-only parameters, which is unsupported.")
                 p.kind = inspect.Parameter.POSITIONAL_ONLY
 
-    def state_parameter_docstring_start(self, line):
+    def state_parameter_docstring_start(self, line: str) -> None:
         self.parameter_docstring_indent = len(self.indent.margin)
         assert self.indent.depth == 3
         return self.next(self.state_parameter_docstring, line)

From d9bbf58afc170185ec4e0af718101db43e65710f Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend@python.org>
Date: Mon, 3 Jul 2023 01:17:51 +0200
Subject: [PATCH 2/2] Address review

---
 Tools/clinic/clinic.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Tools/clinic/clinic.py b/Tools/clinic/clinic.py
index f1a27c76d10c8f..27d3d572868883 100755
--- a/Tools/clinic/clinic.py
+++ b/Tools/clinic/clinic.py
@@ -4508,7 +4508,7 @@ def next(
         if line is not None:
             self.state(line)
 
-    def state_dsl_start(self, line: str | None):
+    def state_dsl_start(self, line: str | None) -> None:
         # self.block = self.ClinicOutputBlock(self)
         if not self.valid_line(line):
             return