Issue #19659: Added documentation for Argument Clinic.

Doc/howto/index.rst

@@ -28,4 +28,5 @@ Currently, the HOWTOs are:
    webservers.rst
    argparse.rst
    ipaddress.rst
+   clinic.rst
 

Misc/NEWS

@@ -345,6 +345,8 @@ Documentation
 Tools/Demos
 -----------
 
+- Issue #19659: Added documentation for Argument Clinic.
+
 - Issue #19976: Argument Clinic METH_NOARGS functions now always
   take two parameters.
 

Modules/zlibmodule.c

@@ -312,9 +312,6 @@ class uint_converter(CConverter):
     type = 'unsigned int'
     converter = 'uint_converter'
 
-class compobject_converter(self_converter):
-    type = "compobject *"
-
 [python]*/
 /*[python checksum: da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
 
@@ -750,7 +747,7 @@ save_unconsumed_input(compobject *self, int err)
 
 zlib.Decompress.decompress
 
-    self: compobject
+    self: self(type="compobject *")
 
     data: Py_buffer
         The binary data to decompress.
@@ -1032,7 +1029,7 @@ PyZlib_flush(compobject *self, PyObject *args)
 /*[clinic]
 zlib.Compress.copy
 
-    self: compobject
+    self: self(type="compobject *")
 
 Return a copy of the compression object.
 [clinic]*/

Tools/clinic/clinic.py

@@ -1296,11 +1296,13 @@ class CConverter(metaclass=CConverterAutoRegister):
     must be keyword-only.
     """
 
+    # The C type to use for this variable.
+    # 'type' should be a Python string specifying the type, e.g. "int".
+    # If this is a pointer type, the type string should end with ' *'.
     type = None
-    format_unit = 'O&'
 
     # The Python default value for this parameter, as a Python value.
-    # Or "unspecified" if there is no default.
+    # Or the magic value "unspecified" if there is no default.
     default = unspecified
 
     # "default" as it should appear in the documentation, as a string.
@@ -1330,9 +1332,32 @@ class CConverter(metaclass=CConverterAutoRegister):
     # (If this is not None, format_unit must be 'O&'.)
     converter = None
 
-    encoding = None
+    # Should Argument Clinic add a '&' before the name of
+    # the variable when passing it into the _impl function?
     impl_by_reference = False
+
+    # Should Argument Clinic add a '&' before the name of
+    # the variable when passing it into PyArg_ParseTuple (AndKeywords)?
     parse_by_reference = True
+
+    #############################################################
+    #############################################################
+    ## You shouldn't need to read anything below this point to ##
+    ## write your own converter functions.                     ##
+    #############################################################
+    #############################################################
+
+    # The "format unit" to specify for this variable when
+    # parsing arguments using PyArg_ParseTuple (AndKeywords).
+    # Custom converters should always use the default value of 'O&'.
+    format_unit = 'O&'
+
+    # What encoding do we want for this variable?  Only used
+    # by format units starting with 'e'.
+    encoding = None
+
+    # Do we want an adjacent '_length' variable for this variable?
+    # Only used by format units ending with '#'.
     length = False
 
     def __init__(self, name, function, default=unspecified, *, doc_default=None, required=False, annotation=unspecified, **kwargs):
@@ -1751,7 +1776,7 @@ class self_converter(CConverter):
     this is the default converter used for "self".
     """
     type = "PyObject *"
-    def converter_init(self):
+    def converter_init(self, *, type=None):
         f = self.function
         if f.kind == CALLABLE:
             if f.cls:
@@ -1766,6 +1791,9 @@ class self_converter(CConverter):
             self.name = "cls"
             self.type = "PyTypeObject *"
 
+        if type:
+            self.type = type
+
     def render(self, parameter, data):
         fail("render() should never be called on self_converter instances")
 
@@ -1787,7 +1815,13 @@ class CReturnConverterAutoRegister(type):
 
 class CReturnConverter(metaclass=CReturnConverterAutoRegister):
 
+    # The C type to use for this variable.
+    # 'type' should be a Python string specifying the type, e.g. "int".
+    # If this is a pointer type, the type string should end with ' *'.
     type = 'PyObject *'
+
+    # The Python default value for this parameter, as a Python value.
+    # Or the magic value "unspecified" if there is no default.
     default = None
 
     def __init__(self, *, doc_default=None, **kwargs):
@@ -1826,6 +1860,16 @@ class CReturnConverter(metaclass=CReturnConverterAutoRegister):
 
 add_c_return_converter(CReturnConverter, 'object')
 
+class NoneType_return_converter(CReturnConverter):
+    def render(self, function, data):
+        self.declare(data)
+        data.return_conversion.append('''
+if (_return_value != Py_None)
+    goto exit;
+return_value = Py_None;
+Py_INCREF(Py_None);
+'''.strip())
+
 class int_return_converter(CReturnConverter):
     type = 'int'
 
@@ -2680,7 +2724,7 @@ def main(argv):
 
                 # print("   ", short_name + "".join(parameters))
             print()
-        print("All converters also accept (doc_default=None, required=False).")
+        print("All converters also accept (doc_default=None, required=False, annotation=None).")
         print("All return converters also accept (doc_default=None).")
         sys.exit(0)