gh-107603: Argument Clinic can emit includes

* Add Clinic.add_include() method
* Add CConverter.include and CConverter.add_include()
* Printer.print_block() gets a second parameter: clinic.
* Remove duplicated declaration of "clinic" global variable.

Tools/clinic/clinic.py

@@ -1074,6 +1074,11 @@ def output_templates(
             del parameters[0]
         converters = [p.converter for p in parameters]
 
+        # Copy includes from parameters to Clinic
+        for converter in converters:
+            if converter.include:
+                clinic.add_include(*converter.include)
+
         has_option_groups = parameters and (parameters[0].group or parameters[-1].group)
         default_return_converter = f.return_converter.type == 'PyObject *'
         new_or_init = f.kind.new_or_init
@@ -2111,7 +2116,9 @@ def print_block(
             self,
             block: Block,
             *,
-            core_includes: bool = False
+            core_includes: bool = False,
+            # needed if core_includes is true
+            clinic: Clinic | None = None,
     ) -> None:
         input = block.input
         output = block.output
@@ -2149,6 +2156,13 @@ def print_block(
 
             """)
 
+            if clinic:
+                # Emit optional includes
+                for include, reason in sorted(clinic.includes.items()):
+                    line = f'#include "{include}"'
+                    line = line.ljust(35) + f'// {reason}\n'
+                    output += line
+
         input = ''.join(block.input)
         output += ''.join(block.output)
         if output:
@@ -2291,7 +2305,7 @@ def __init__(self, clinic: Clinic) -> None: ...
     def parse(self, block: Block) -> None: ...
 
 
-clinic = None
+clinic : Clinic | None = None
 class Clinic:
 
     presets_text = """
@@ -2357,6 +2371,9 @@ def __init__(
         self.modules: ModuleDict = {}
         self.classes: ClassDict = {}
         self.functions: list[Function] = []
+        # dict: include name => reason
+        # Example: 'pycore_long.h' => '_PyLong_UnsignedShort_Converter()'
+        self.includes: dict[str, str] = {}
 
         self.line_prefix = self.line_suffix = ''
 
@@ -2415,6 +2432,12 @@ def __init__(
         global clinic
         clinic = self
 
+    def add_include(self, name: str, reason: str) -> None:
+        if name in self.includes:
+            # Mention a single reason is enough, no need to list all of them
+            return
+        self.includes[name] = reason
+
     def add_destination(
             self,
             name: str,
@@ -2490,7 +2513,7 @@ def parse(self, input: str) -> str:
 
                     block.input = 'preserve\n'
                     printer_2 = BlockPrinter(self.language)
-                    printer_2.print_block(block, core_includes=True)
+                    printer_2.print_block(block, core_includes=True, clinic=self)
                     write_file(destination.filename, printer_2.f.getvalue())
                     continue
 
@@ -3035,6 +3058,9 @@ class CConverter(metaclass=CConverterAutoRegister):
     # Only set by self_converter.
     signature_name: str | None = None
 
+    # Optional #include "name"  // reason
+    include: tuple[str, str] | None = None
+
     # keep in sync with self_converter.__init__!
     def __init__(self,
              # Positional args:
@@ -3339,6 +3365,11 @@ def parser_name(self) -> str:
         else:
             return self.name
 
+    def add_include(self, name: str, reason: str) -> None:
+        if self.include:
+            raise ValueError("a converter only supports a single include")
+        self.include = (name, reason)
+
 type_checks = {
     '&PyLong_Type': ('PyLong_Check', 'int'),
     '&PyTuple_Type': ('PyTuple_Check', 'tuple'),
@@ -5958,9 +5989,6 @@ def do_post_block_processing_cleanup(self, lineno: int) -> None:
 }
 
 
-clinic = None
-
-
 def create_cli() -> argparse.ArgumentParser:
     cmdline = argparse.ArgumentParser(
         prog="clinic.py",