gh-113317: Argument Clinic: Add libclinic.converters module (#117315)

Move the following converter classes to libclinic.converters:

* PyByteArrayObject_converter
* PyBytesObject_converter
* Py_UNICODE_converter
* Py_buffer_converter
* Py_complex_converter
* Py_ssize_t_converter
* bool_converter
* byte_converter
* char_converter
* defining_class_converter
* double_converter
* fildes_converter
* float_converter
* int_converter
* long_converter
* long_long_converter
* object_converter
* self_converter
* short_converter
* size_t_converter
* slice_index_converter
* str_converter
* unicode_converter
* unsigned_char_converter
* unsigned_int_converter
* unsigned_long_converter
* unsigned_long_long_converter
* unsigned_short_converter

Move also the following classes to libclinic.converters:

* buffer
* robuffer
* rwbuffer

Move the following functions to libclinic.converters:

* correct_name_for_self()
* r()
* str_converter_key()

Move Null and NULL to libclinic.utils.

Lib/test/test_clinic.py

@@ -17,6 +17,7 @@ import unittest
 test_tools.skip_if_missing('clinic')
 with test_tools.imports_under_tool('clinic'):
     import libclinic
+    from libclinic.converters import int_converter, str_converter
     import clinic
     from clinic import DSLParser
 
@@ -924,7 +925,7 @@ class ClinicParserTest(TestCase):
         self.assertEqual(2, len(function.parameters))
         p = function.parameters['path']
         self.assertEqual('path', p.name)
-        self.assertIsInstance(p.converter, clinic.int_converter)
+        self.assertIsInstance(p.converter, int_converter)
 
     def test_param_default(self):
         function = self.parse_function("""
@@ -1023,7 +1024,7 @@ class ClinicParserTest(TestCase):
         """)
         self.assertEqual(3, len(function.parameters))
         conv = function.parameters['something_else'].converter
-        self.assertIsInstance(conv, clinic.str_converter)
+        self.assertIsInstance(conv, str_converter)
 
     def test_param_default_parameters_out_of_order(self):
         err = (
@@ -2040,7 +2041,7 @@ class ClinicParserTest(TestCase):
         block = self.parse('module os\nos.access\n   path: "s"')
         module, function = block.signatures
         conv = (function.parameters['path']).converter
-        self.assertIsInstance(conv, clinic.str_converter)
+        self.assertIsInstance(conv, str_converter)
 
     def test_legacy_converters_non_string_constant_annotation(self):
         err = "Annotations must be either a name, a function call, or a string"

Tools/clinic/libclinic/__init__.py

@@ -25,13 +25,15 @@ from .identifiers import (
 )
 from .utils import (
     FormatCounterFormatter,
+    NULL,
+    Null,
+    Sentinels,
+    VersionTuple,
     compute_checksum,
     create_regex,
-    write_file,
-    VersionTuple,
-    Sentinels,
-    unspecified,
     unknown,
+    unspecified,
+    write_file,
 )
 
 
@@ -61,13 +63,15 @@ __all__ = [
 
     # Utility functions
     "FormatCounterFormatter",
+    "NULL",
+    "Null",
+    "Sentinels",
+    "VersionTuple",
     "compute_checksum",
     "create_regex",
-    "write_file",
-    "VersionTuple",
-    "Sentinels",
-    "unspecified",
     "unknown",
+    "unspecified",
+    "write_file",
 ]
 
 

Tools/clinic/libclinic/converter.py

@@ -531,3 +531,19 @@ converters: ConverterDict = {}
 # these callables follow the same rules as those for "converters" above.
 # note however that they will never be called with keyword-only parameters.
 legacy_converters: ConverterDict = {}
+
+
+def add_legacy_c_converter(
+    format_unit: str,
+    **kwargs: Any
+) -> Callable[[CConverterClassT], CConverterClassT]:
+    def closure(f: CConverterClassT) -> CConverterClassT:
+        added_f: Callable[..., CConverter]
+        if not kwargs:
+            added_f = f
+        else:
+            added_f = functools.partial(f, **kwargs)
+        if format_unit:
+            legacy_converters[format_unit] = added_f
+        return f
+    return closure

Tools/clinic/libclinic/function.py

@@ -6,8 +6,9 @@ import functools
 import inspect
 from typing import Final, Any, TYPE_CHECKING
 if TYPE_CHECKING:
-    from clinic import Clinic, CReturnConverter, self_converter
+    from clinic import Clinic, CReturnConverter
     from libclinic.converter import CConverter
+    from libclinic.converters import self_converter
 
 from libclinic import VersionTuple, unspecified
 

Tools/clinic/libclinic/utils.py

@@ -82,3 +82,12 @@ class Sentinels(enum.Enum):
 
 unspecified: Final = Sentinels.unspecified
 unknown: Final = Sentinels.unknown
+
+
+# This one needs to be a distinct class, unlike the other two
+class Null:
+    def __repr__(self) -> str:
+        return '<Null>'
+
+
+NULL = Null()