gh-106368: Increase Argument Clinic test coverage (#107582)

Add tests for DSL parser state machine and docstring formatting

2 files changed, 394 insertions, 2 deletions

diff --git a/Lib/test/clinic.test.c b/Lib/test/clinic.test.c
index a49c2e7..d2ad1a0 100644
--- a/Lib/test/clinic.test.c
+++ b/Lib/test/clinic.test.c
@@ -5264,3 +5264,203 @@ Test__pyarg_parsestackandkeywords_impl(TestObj *self, PyTypeObject *cls,
                                        const char *key,
                                        Py_ssize_t key_length)
 /*[clinic end generated code: output=4fda8a7f2547137c input=fc72ef4b4cfafabc]*/
+
+
+/*[clinic input]
+Test.__init__ -> long
+Test overriding the __init__ return converter
+[clinic start generated code]*/
+
+PyDoc_STRVAR(Test___init____doc__,
+"Test()\n"
+"--\n"
+"\n"
+"Test overriding the __init__ return converter");
+
+static long
+Test___init___impl(TestObj *self);
+
+static int
+Test___init__(PyObject *self, PyObject *args, PyObject *kwargs)
+{
+    int return_value = -1;
+    PyTypeObject *base_tp = TestType;
+    long _return_value;
+
+    if ((Py_IS_TYPE(self, base_tp) ||
+         Py_TYPE(self)->tp_new == base_tp->tp_new) &&
+        !_PyArg_NoPositional("Test", args)) {
+        goto exit;
+    }
+    if ((Py_IS_TYPE(self, base_tp) ||
+         Py_TYPE(self)->tp_new == base_tp->tp_new) &&
+        !_PyArg_NoKeywords("Test", kwargs)) {
+        goto exit;
+    }
+    _return_value = Test___init___impl((TestObj *)self);
+    if ((_return_value == -1) && PyErr_Occurred()) {
+        goto exit;
+    }
+    return_value = PyLong_FromLong(_return_value);
+
+exit:
+    return return_value;
+}
+
+static long
+Test___init___impl(TestObj *self)
+/*[clinic end generated code: output=daf6ee12c4e443fb input=311af0dc7f17e8e9]*/
+
+
+/*[clinic input]
+fn_with_default_binop_expr
+    arg: object(c_default='CONST_A + CONST_B') = a+b
+[clinic start generated code]*/
+
+PyDoc_STRVAR(fn_with_default_binop_expr__doc__,
+"fn_with_default_binop_expr($module, /, arg=a+b)\n"
+"--\n"
+"\n");
+
+#define FN_WITH_DEFAULT_BINOP_EXPR_METHODDEF    \
+    {"fn_with_default_binop_expr", _PyCFunction_CAST(fn_with_default_binop_expr), METH_FASTCALL|METH_KEYWORDS, fn_with_default_binop_expr__doc__},
+
+static PyObject *
+fn_with_default_binop_expr_impl(PyObject *module, PyObject *arg);
+
+static PyObject *
+fn_with_default_binop_expr(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
+{
+    PyObject *return_value = NULL;
+    #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
+
+    #define NUM_KEYWORDS 1
+    static struct {
+        PyGC_Head _this_is_not_used;
+        PyObject_VAR_HEAD
+        PyObject *ob_item[NUM_KEYWORDS];
+    } _kwtuple = {
+        .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
+        .ob_item = { &_Py_ID(arg), },
+    };
+    #undef NUM_KEYWORDS
+    #define KWTUPLE (&_kwtuple.ob_base.ob_base)
+
+    #else  // !Py_BUILD_CORE
+    #  define KWTUPLE NULL
+    #endif  // !Py_BUILD_CORE
+
+    static const char * const _keywords[] = {"arg", NULL};
+    static _PyArg_Parser _parser = {
+        .keywords = _keywords,
+        .fname = "fn_with_default_binop_expr",
+        .kwtuple = KWTUPLE,
+    };
+    #undef KWTUPLE
+    PyObject *argsbuf[1];
+    Py_ssize_t noptargs = nargs + (kwnames ? PyTuple_GET_SIZE(kwnames) : 0) - 0;
+    PyObject *arg = CONST_A + CONST_B;
+
+    args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 0, 1, 0, argsbuf);
+    if (!args) {
+        goto exit;
+    }
+    if (!noptargs) {
+        goto skip_optional_pos;
+    }
+    arg = args[0];
+skip_optional_pos:
+    return_value = fn_with_default_binop_expr_impl(module, arg);
+
+exit:
+    return return_value;
+}
+
+static PyObject *
+fn_with_default_binop_expr_impl(PyObject *module, PyObject *arg)
+/*[clinic end generated code: output=018672772e4092ff input=1b55c8ae68d89453]*/
+
+/*[python input]
+class Custom_converter(CConverter):
+    type = "str"
+    default = "Hello!"
+    converter = "c_converter_func"
+[python start generated code]*/
+/*[python end generated code: output=da39a3ee5e6b4b0d input=d612708f0efb8e3c]*/
+
+/*[clinic input]
+docstr_fallback_to_converter_default
+    a: Custom
+Check docstring default value fallback.
+
+Verify that the docstring formatter fetches the default
+value from the converter if no 'py_default' is found.
+The signature should have the default a='Hello!',
+as given by the Custom converter.
+[clinic start generated code]*/
+
+PyDoc_STRVAR(docstr_fallback_to_converter_default__doc__,
+"docstr_fallback_to_converter_default($module, /, a=\'Hello!\')\n"
+"--\n"
+"\n"
+"Check docstring default value fallback.\n"
+"\n"
+"Verify that the docstring formatter fetches the default\n"
+"value from the converter if no \'py_default\' is found.\n"
+"The signature should have the default a=\'Hello!\',\n"
+"as given by the Custom converter.");
+
+#define DOCSTR_FALLBACK_TO_CONVERTER_DEFAULT_METHODDEF    \
+    {"docstr_fallback_to_converter_default", _PyCFunction_CAST(docstr_fallback_to_converter_default), METH_FASTCALL|METH_KEYWORDS, docstr_fallback_to_converter_default__doc__},
+
+static PyObject *
+docstr_fallback_to_converter_default_impl(PyObject *module, str a);
+
+static PyObject *
+docstr_fallback_to_converter_default(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
+{
+    PyObject *return_value = NULL;
+    #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
+
+    #define NUM_KEYWORDS 1
+    static struct {
+        PyGC_Head _this_is_not_used;
+        PyObject_VAR_HEAD
+        PyObject *ob_item[NUM_KEYWORDS];
+    } _kwtuple = {
+        .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
+        .ob_item = { &_Py_ID(a), },
+    };
+    #undef NUM_KEYWORDS
+    #define KWTUPLE (&_kwtuple.ob_base.ob_base)
+
+    #else  // !Py_BUILD_CORE
+    #  define KWTUPLE NULL
+    #endif  // !Py_BUILD_CORE
+
+    static const char * const _keywords[] = {"a", NULL};
+    static _PyArg_Parser _parser = {
+        .keywords = _keywords,
+        .fname = "docstr_fallback_to_converter_default",
+        .kwtuple = KWTUPLE,
+    };
+    #undef KWTUPLE
+    PyObject *argsbuf[1];
+    str a;
+
+    args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 1, 1, 0, argsbuf);
+    if (!args) {
+        goto exit;
+    }
+    if (!c_converter_func(args[0], &a)) {
+        goto exit;
+    }
+    return_value = docstr_fallback_to_converter_default_impl(module, a);
+
+exit:
+    return return_value;
+}
+
+static PyObject *
+docstr_fallback_to_converter_default_impl(PyObject *module, str a)
+/*[clinic end generated code: output=ae24a9c6f60ee8a6 input=0cbe6a4d24bc2274]*/
diff --git a/Lib/test/test_clinic.py b/Lib/test/test_clinic.py
index 127008d..2f94566 100644
--- a/Lib/test/test_clinic.py
+++ b/Lib/test/test_clinic.py
@@ -385,6 +385,37 @@ class ClinicWholeFileTest(TestCase):
         """
         self.expect_failure(block, err)
 
+    def test_clone_mismatch(self):
+        err = "'kind' of function and cloned function don't match!"
+        block = """
+            /*[clinic input]
+            module m
+            @classmethod
+            m.f1
+                a: object
+            [clinic start generated code]*/
+            /*[clinic input]
+            @staticmethod
+            m.f2 = m.f1
+            [clinic start generated code]*/
+        """
+        self.expect_failure(block, err, lineno=9)
+
+    def test_badly_formed_return_annotation(self):
+        err = "Badly formed annotation for m.f: 'Custom'"
+        block = """
+            /*[python input]
+            class Custom_return_converter(CReturnConverter):
+                def __init__(self):
+                    raise ValueError("abc")
+            [python start generated code]*/
+            /*[clinic input]
+            module m
+            m.f -> Custom
+            [clinic start generated code]*/
+        """
+        self.expect_failure(block, err, lineno=8)
+
 
 class ClinicGroupPermuterTest(TestCase):
     def _test(self, l, m, r, output):
@@ -642,7 +673,7 @@ class ClinicParserTest(TestCase):
         p = function.parameters['follow_symlinks']
         self.assertEqual(True, p.default)
 
-    def test_param_default_expression(self):
+    def test_param_default_expr_named_constant(self):
         function = self.parse_function("""
             module os
             os.access
@@ -663,6 +694,17 @@ class ClinicParserTest(TestCase):
         """
         self.expect_failure(block, err, lineno=2)
 
+    def test_param_default_expr_binop(self):
+        err = (
+            "When you specify an expression ('a + b') as your default value,\n"
+            "you MUST specify a valid c_default."
+        )
+        block = """
+            fn
+                follow_symlinks: int = a + b
+        """
+        self.expect_failure(block, err, lineno=1)
+
     def test_param_no_docstring(self):
         function = self.parse_function("""
             module os
@@ -1241,6 +1283,63 @@ class ClinicParserTest(TestCase):
                 Nested docstring here, goeth.
         """)
 
+    def test_docstring_only_summary(self):
+        function = self.parse_function("""
+              module m
+              m.f
+              summary
+        """)
+        self.checkDocstring(function, """
+            f($module, /)
+            --
+
+            summary
+        """)
+
+    def test_docstring_empty_lines(self):
+        function = self.parse_function("""
+              module m
+              m.f
+
+
+        """)
+        self.checkDocstring(function, """
+            f($module, /)
+            --
+        """)
+
+    def test_docstring_explicit_params_placement(self):
+        function = self.parse_function("""
+              module m
+              m.f
+                a: int
+                    Param docstring for 'a' will be included
+                b: int
+                c: int
+                    Param docstring for 'c' will be included
+              This is the summary line.
+
+              We'll now place the params section here:
+              {parameters}
+              And now for something completely different!
+              (Note the added newline)
+        """)
+        self.checkDocstring(function, """
+            f($module, /, a, b, c)
+            --
+
+            This is the summary line.
+
+            We'll now place the params section here:
+              a
+                Param docstring for 'a' will be included
+              c
+                Param docstring for 'c' will be included
+
+            And now for something completely different!
+            (Note the added newline)
+        """)
+
     def test_indent_stack_no_tabs(self):
         block = """
             module foo
@@ -1471,7 +1570,100 @@ class ClinicParserTest(TestCase):
             test.fn
                 a as 17a: int
         """
-        self.expect_failure(block, err)
+        self.expect_failure(block, err, lineno=2)
+
+    def test_cannot_convert_special_method(self):
+        err = "__len__ is a special method and cannot be converted"
+        block = """
+            class T "" ""
+            T.__len__
+        """
+        self.expect_failure(block, err, lineno=1)
+
+    def test_cannot_specify_pydefault_without_default(self):
+        err = "You can't specify py_default without specifying a default value!"
+        block = """
+            fn
+                a: object(py_default='NULL')
+        """
+        self.expect_failure(block, err, lineno=1)
+
+    def test_vararg_cannot_take_default_value(self):
+        err = "Vararg can't take a default value!"
+        block = """
+            fn
+                *args: object = None
+        """
+        self.expect_failure(block, err, lineno=1)
+
+    def test_invalid_legacy_converter(self):
+        err = "fhi is not a valid legacy converter"
+        block = """
+            fn
+                a: 'fhi'
+        """
+        self.expect_failure(block, err, lineno=1)
+
+    def test_parent_class_or_module_does_not_exist(self):
+        err = "Parent class or module z does not exist"
+        block = """
+            module m
+            z.func
+        """
+        self.expect_failure(block, err, lineno=1)
+
+    def test_duplicate_param_name(self):
+        err = "You can't have two parameters named 'a'"
+        block = """
+            module m
+            m.func
+                a: int
+                a: float
+        """
+        self.expect_failure(block, err, lineno=3)
+
+    def test_param_requires_custom_c_name(self):
+        err = "Parameter 'module' requires a custom C name"
+        block = """
+            module m
+            m.func
+                module: int
+        """
+        self.expect_failure(block, err, lineno=2)
+
+    def test_state_func_docstring_assert_no_group(self):
+        err = "Function func has a ] without a matching [."
+        block = """
+            module m
+            m.func
+                ]
+            docstring
+        """
+        self.expect_failure(block, err, lineno=2)
+
+    def test_state_func_docstring_no_summary(self):
+        err = "Docstring for m.func does not have a summary line!"
+        block = """
+            module m
+            m.func
+            docstring1
+            docstring2
+        """
+        self.expect_failure(block, err, lineno=0)
+
+    def test_state_func_docstring_only_one_param_template(self):
+        err = "You may not specify {parameters} more than once in a docstring!"
+        block = """
+            module m
+            m.func
+            docstring summary
+
+            these are the params:
+                {parameters}
+            these are the params again:
+                {parameters}
+        """
+        self.expect_failure(block, err, lineno=0)
 
 
 class ClinicExternalTest(TestCase):