pythongh-117431: Argument Clinic: copy forced text signature when cloning (python#117591)

Author: erlend-aasland

Lib/test/test_clinic.py

@@ -5,7 +5,7 @@
 from functools import partial
 from test import support, test_tools
 from test.support import os_helper
-from test.support.os_helper import TESTFN, unlink
+from test.support.os_helper import TESTFN, unlink, rmtree
 from textwrap import dedent
 from unittest import TestCase
 import inspect
@@ -662,6 +662,61 @@ class C "void *" ""
         err = "Illegal C basename: '.illegal.'"
         self.expect_failure(block, err, lineno=7)
 
+    def test_cloned_forced_text_signature(self):
+        block = dedent("""
+            /*[clinic input]
+            @text_signature "($module, a[, b])"
+            src
+                a: object
+                    param a
+                b: object = NULL
+                /
+
+            docstring
+            [clinic start generated code]*/
+
+            /*[clinic input]
+            dst = src
+            [clinic start generated code]*/
+        """)
+        self.clinic.parse(block)
+        self.addCleanup(rmtree, "clinic")
+        funcs = self.clinic.functions
+        self.assertEqual(len(funcs), 2)
+
+        src_docstring_lines = funcs[0].docstring.split("\n")
+        dst_docstring_lines = funcs[1].docstring.split("\n")
+
+        # Signatures are copied.
+        self.assertEqual(src_docstring_lines[0], "src($module, a[, b])")
+        self.assertEqual(dst_docstring_lines[0], "dst($module, a[, b])")
+
+        # Param docstrings are copied.
+        self.assertIn("    param a", src_docstring_lines)
+        self.assertIn("    param a", dst_docstring_lines)
+
+        # Docstrings are not copied.
+        self.assertIn("docstring", src_docstring_lines)
+        self.assertNotIn("docstring", dst_docstring_lines)
+
+    def test_cloned_forced_text_signature_illegal(self):
+        block = """
+            /*[clinic input]
+            @text_signature "($module, a[, b])"
+            src
+                a: object
+                b: object = NULL
+                /
+            [clinic start generated code]*/
+
+            /*[clinic input]
+            @text_signature "($module, a_override[, b])"
+            dst = src
+            [clinic start generated code]*/
+        """
+        err = "Cannot use @text_signature when cloning a function"
+        self.expect_failure(block, err, lineno=11)
+
 
 class ParseFileUnitTest(TestCase):
     def expect_parsing_failure(

Objects/clinic/unicodeobject.c.h

@@ -666,6 +666,8 @@ def state_modulename_name(self, line: str) -> None:
         if equals:
             existing = existing.strip()
             if libclinic.is_legal_py_identifier(existing):
+                if self.forced_text_signature:
+                    fail("Cannot use @text_signature when cloning a function")
                 # we're cloning!
                 names = self.parse_function_names(before)
                 return self.parse_cloned_function(names, existing)
@@ -689,7 +691,8 @@ def state_modulename_name(self, line: str) -> None:
             kind=self.kind,
             coexist=self.coexist,
             critical_section=self.critical_section,
-            target_critical_section=self.target_critical_section
+            target_critical_section=self.target_critical_section,
+            forced_text_signature=self.forced_text_signature
         )
         self.add_function(func)
 
@@ -1324,13 +1327,14 @@ def state_function_docstring(self, line: str) -> None:
 
         self.docstring_append(self.function, line)
 
+    @staticmethod
     def format_docstring_signature(
-        self, f: Function, parameters: list[Parameter]
+        f: Function, parameters: list[Parameter]
     ) -> str:
         lines = []
         lines.append(f.displayname)
-        if self.forced_text_signature:
-            lines.append(self.forced_text_signature)
+        if f.forced_text_signature:
+            lines.append(f.forced_text_signature)
         elif f.kind in {GETTER, SETTER}:
             # @getter and @setter do not need signatures like a method or a function.
             return ''

Tools/clinic/libclinic/dsl_parser.py

@@ -107,6 +107,7 @@ class Function:
     # functions with optional groups because we can't represent
     # those accurately with inspect.Signature in 3.4.
     docstring_only: bool = False
+    forced_text_signature: str | None = None
     critical_section: bool = False
     target_critical_section: list[str] = dc.field(default_factory=list)