gh-104389: Add 'unused' keyword to Argument Clinic C converters

Doc/howto/clinic.rst

@@ -775,6 +775,9 @@ All Argument Clinic converters accept the following arguments:
     because :pep:`8` mandates that the Python library may not use
     annotations.
 
+  ``unused``
+    Wrap the argument with :c:macro:`Py_UNUSED` in the impl function signature.
+
 In addition, some converters accept additional arguments.  Here is a list
 of these arguments, along with their meanings:
 

Misc/NEWS.d/next/Tools-Demos/2023-05-11-15-12-11.gh-issue-104389.EiOhB3.rst

@@ -0,0 +1,2 @@
+Argument Clinic C converters now accept the ``unused`` keyword, for wrapping
+a parameter with :c:macro:`Py_UNUSED`. Patch by Erlend E. Aasland.

Modules/_io/textio.c

@@ -69,8 +69,8 @@ _io__TextIOBase_detach_impl(PyObject *self, PyTypeObject *cls)
 /*[clinic input]
 _io._TextIOBase.read
     cls: defining_class
+    size: int(unused=True) = -1
     /
-    *args: object
 
 Read at most size characters from stream.
 
@@ -79,8 +79,9 @@ If size is negative or omitted, read until EOF.
 [clinic start generated code]*/
 
 static PyObject *
-_io__TextIOBase_read_impl(PyObject *self, PyTypeObject *cls, PyObject *args)
-/*[clinic end generated code: output=3adf28998831f461 input=cee1e84664a20de0]*/
+_io__TextIOBase_read_impl(PyObject *self, PyTypeObject *cls,
+                          int Py_UNUSED(size))
+/*[clinic end generated code: output=51a5178a309ce647 input=f5e37720f9fc563f]*/
 {
     _PyIO_State *state = IO_STATE();
     return _unsupported(state, "read");

Tools/clinic/clinic.py

@@ -2599,6 +2599,9 @@ class CConverter(metaclass=CConverterAutoRegister):
     # Every non-abstract subclass should supply a valid value.
     c_ignored_default = 'NULL'
 
+    # If true, wrap with Py_UNUSED.
+    unused = False
+
     # The C converter *function* to be used, if any.
     # (If this is not None, format_unit must be 'O&'.)
     converter = None
@@ -2651,9 +2654,22 @@ class CConverter(metaclass=CConverterAutoRegister):
     signature_name = None
 
     # keep in sync with self_converter.__init__!
-    def __init__(self, name, py_name, function, default=unspecified, *, c_default=None, py_default=None, annotation=unspecified, **kwargs):
+    def __init__(self,
+             # Positional args:
+             name,
+             py_name,
+             function,
+             default=unspecified,
+             *,  # Keyword only args:
+             c_default=None,
+             py_default=None,
+             annotation=unspecified,
+             unused=False,
+             **kwargs
+    ):
         self.name = ensure_legal_c_identifier(name)
         self.py_name = py_name
+        self.unused = unused
 
         if default is not unspecified:
             if self.default_type and not isinstance(default, (self.default_type, Unknown)):
@@ -2800,6 +2816,8 @@ def simple_declaration(self, by_reference=False, *, in_parser=False):
             name = self.parser_name
         else:
             name = self.name
+            if self.unused:
+                name = f"Py_UNUSED({name})"
         prototype.append(name)
         return "".join(prototype)