gh-117431: Argument Clinic: copy forced text signature when cloning

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(

Tools/clinic/libclinic/dsl_parser.py

@@ -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/function.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)