gh-155263: Add the --list option to Argument Clinic (GH-155264)

It prints the modules, classes and functions which Argument Clinic
defines in the specified files, each function with its signature.

Author: serhiy-storchaka

Lib/test/test_clinic.py

@@ -3681,6 +3681,163 @@ def test_cli_converters_no_converters(self):
                 f.write("/*[clinic input]\n[clinic start generated code]*/\n")
             self.assertEqual(self.expect_success("--converters", fn), "")
 
+    LIST_CODE = dedent("""
+        /*[clinic input]
+        func
+            a: int
+            /
+
+        Docstring.
+        [clinic start generated code]*/
+
+        /*[clinic input]
+        cloned = func
+        [clinic start generated code]*/
+
+        /*[clinic input]
+        module m
+        class m.C "void *" ""
+        class m.C.D "void *" ""
+        [clinic start generated code]*/
+
+        /*[clinic input]
+        m.C.meth
+            self: self(type="void *")
+            a: object
+            [
+            b: object
+            ]
+            /
+
+        Docstring.
+        [clinic start generated code]*/
+
+        /*[clinic input]
+        @classmethod
+        m.C.__new__
+            a: object
+
+        Docstring.
+        [clinic start generated code]*/
+
+        /*[clinic input]
+        @getter
+        m.C.prop
+        [clinic start generated code]*/
+
+        /*[clinic input]
+        @setter
+        m.C.prop
+        [clinic start generated code]*/
+
+        /*[clinic input]
+        m.C.D.meth
+            self: self(type="void *")
+
+        Docstring.
+        [clinic start generated code]*/
+    """)
+
+    def make_list_file(self, tmp_dir):
+        fn = os.path.join(tmp_dir, "test.c")
+        with open(fn, "w", encoding="utf-8") as f:
+            f.write(self.LIST_CODE)
+        return fn
+
+    LIST_OUTPUT = [
+        "  func($module, a, /)",
+        "  cloned($module, a, /)",
+        "  module m",
+        "    class m.C",
+        # A signature with an option group is only for the docstring.
+        "      m.C.meth(a, [b])",
+        "      m.C(a)",
+        "      getter m.C.prop",
+        "      setter m.C.prop",
+        "      class m.C.D",
+        "        m.C.D.meth($self, /)",
+    ]
+
+    def test_cli_list(self):
+        with os_helper.temp_dir() as tmp_dir:
+            fn = self.make_list_file(tmp_dir)
+            pre_mtime = os.stat(fn).st_mtime_ns
+            out = self.expect_success("--list", fn)
+            self.assertEqual(out.splitlines(), [fn] + self.LIST_OUTPUT)
+            # Nothing is written.
+            with open(fn, encoding="utf-8") as f:
+                self.assertEqual(f.read(), self.LIST_CODE)
+            self.assertEqual(os.stat(fn).st_mtime_ns, pre_mtime)
+            self.assertEqual(os.listdir(tmp_dir), ["test.c"])
+
+    def test_cli_list_no_clinic_block(self):
+        with os_helper.temp_dir() as tmp_dir:
+            fn = os.path.join(tmp_dir, "test.c")
+            with open(fn, "w", encoding="utf-8") as f:
+                f.write("int x;\n")
+            self.assertEqual(self.expect_success("--list", fn), "")
+
+    def test_cli_list_no_definitions(self):
+        with os_helper.temp_dir() as tmp_dir:
+            fn = os.path.join(tmp_dir, "test.c")
+            with open(fn, "w", encoding="utf-8") as f:
+                f.write("/*[clinic input]\n[clinic start generated code]*/\n")
+            self.assertEqual(self.expect_success("--list", fn), "")
+
+    def test_cli_list_make(self):
+        with os_helper.temp_dir() as tmp_dir:
+            fn = self.make_list_file(tmp_dir)
+            out = self.expect_success("--list", "--make", "--srcdir", tmp_dir)
+            self.assertEqual(out.splitlines(), [fn] + self.LIST_OUTPUT)
+            self.assertEqual(os.listdir(tmp_dir), ["test.c"])
+
+    def test_cli_list_verbose(self):
+        with os_helper.temp_dir() as tmp_dir:
+            fn = self.make_list_file(tmp_dir)
+            # The progress does not mix with the report.
+            out, err, code = self.run_clinic("-v", "--list", fn)
+            self.assertEqual(code, 0)
+            self.assertEqual(err.splitlines(), [fn])
+            self.assertEqual(out.splitlines(), [fn] + self.LIST_OUTPUT)
+
+    def test_cli_list_checksum_mismatch(self):
+        with os_helper.temp_dir() as tmp_dir:
+            fn = self.make_list_file(tmp_dir)
+            with open(fn, "a", encoding="utf-8") as f:
+                f.write("/*[clinic end generated code: "
+                        "output=0123456789abcdef input=fedcba9876543210]*/\n")
+            _, err = self.expect_failure("--list", fn)
+            self.assertIn("Checksum mismatch!", err)
+            # The check is skipped with --force.
+            out = self.expect_success("-f", "--list", fn)
+            self.assertEqual(out.splitlines(), [fn] + self.LIST_OUTPUT)
+            self.assertEqual(os.listdir(tmp_dir), ["test.c"])
+
+    def test_cli_list_external(self):
+        # A file which uses getters, setters and nested classes.
+        source = support.findfile('clinic.test.c')
+        out = self.expect_success("--list", source)
+        lines = out.splitlines()
+        self.assertEqual(lines[0], source)
+        for line in ("  class Test",
+                     "    getter Test.property",
+                     "    setter Test.property",
+                     "    Test.class_method($type, /)",
+                     "  module m",
+                     "    class m.T"):
+            with self.subTest(line=line):
+                self.assertIn(line, lines)
+
+    def test_cli_fail_list_and_dry_run(self):
+        for opt in "--dry-run", "--diff":
+            with self.subTest(opt=opt):
+                _, err = self.expect_failure("--list", opt, "test.c")
+                self.assertIn("can't use --dry-run or --diff with --list", err)
+
+    def test_cli_fail_list_and_converters(self):
+        _, err = self.expect_failure("--list", "--converters", "test.c")
+        self.assertIn("can't use --converters with --list", err)
+
     def test_cli_fail_directory(self):
         with os_helper.temp_dir() as tmp_dir:
             subdir = os.path.join(tmp_dir, "test.c")

Misc/NEWS.d/next/Tools-Demos/2026-08-06-08-32-53.gh-issue-155263.RCcjtk.rst

@@ -0,0 +1,3 @@
+Add the ``--list`` option to Argument Clinic.
+It prints the modules, classes and functions which Argument Clinic defines in
+the specified files, each function with its signature.

Tools/clinic/libclinic/cli.py

@@ -22,6 +22,9 @@
     return_converters, ReturnConverterType)
 from libclinic.clanguage import CLanguage
 from libclinic.app import Clinic
+from libclinic.dsl_parser import render_text_signature
+from libclinic.function import (
+    Class, Definition, Module, GETTER, SETTER, walk_definitions)
 
 
 # TODO:
@@ -54,7 +57,7 @@ def parse_file(
         output: str | None = None,
         verify: bool = True,
         writer: libclinic.FileWriter | None = None,
-) -> None:
+) -> Clinic | None:
     if not output:
         output = filename
     if writer is None:
@@ -78,7 +81,7 @@ def parse_file(
     # exit quickly if there are no clinic markers in the file
     find_start_re = BlockParser("", language).find_start_re
     if not find_start_re.search(raw):
-        return
+        return None
 
     if LIMITED_CAPI_REGEX.search(raw):
         limited_capi = True
@@ -97,6 +100,31 @@ def parse_file(
     writer.update_times(output,
                         [fn for fn, _ in files if fn != output],
                         any(changed for _, changed in files))
+    return clinic
+
+
+def format_definition(depth: int, name: str, definition: Definition) -> str:
+    indent = "  " * (depth + 1)
+    if isinstance(definition, Module):
+        return f"{indent}module {name}"
+    if isinstance(definition, Class):
+        return f"{indent}class {name}"
+    if definition.kind is GETTER:
+        return f"{indent}getter {name}"
+    if definition.kind is SETTER:
+        return f"{indent}setter {name}"
+    signature = render_text_signature(definition, definition.render_parameters,
+                                      name=name, line_width=None)
+    return indent + signature
+
+
+def print_definitions(clinic: Clinic) -> None:
+    """Print the modules, classes and functions defined in the parsed file."""
+    lines = [format_definition(depth, name, definition)
+             for depth, name, definition in walk_definitions(clinic)]
+    if lines:
+        print(clinic.filename)
+        print("\n".join(lines))
 
 
 def create_cli() -> argparse.ArgumentParser:
@@ -126,6 +154,10 @@ def create_cli() -> argparse.ArgumentParser:
                                "and return converters; if files are "
                                "specified, print only the converters "
                                "which they define"))
+    cmdline.add_argument("--list", action='store_true',
+                         help=("don't write any file, only list the modules, "
+                               "classes and functions which the specified "
+                               "files define, with their signatures"))
     cmdline.add_argument("--make", action='store_true',
                          help="walk --srcdir to run over all relevant files")
     cmdline.add_argument("--srcdir", type=str, default=os.curdir,
@@ -252,7 +284,7 @@ def run_clinic(parser: argparse.ArgumentParser, ns: argparse.Namespace) -> None:
     dry_run = ns.dry_run or ns.diff
     # The report is written to the standard output, so the progress
     # is written to the standard error stream to not mix them.
-    verbose_file = sys.stderr if dry_run else sys.stdout
+    verbose_file = sys.stderr if dry_run or ns.list else sys.stdout
 
     filenames: Iterable[str]
     if ns.make:
@@ -268,6 +300,12 @@ def run_clinic(parser: argparse.ArgumentParser, ns: argparse.Namespace) -> None:
             parser.error("can't use -o with multiple filenames")
         filenames = ns.filename
 
+    if ns.list:
+        if dry_run:
+            parser.error("can't use --dry-run or --diff with --list")
+        if ns.converters:
+            parser.error("can't use --converters with --list")
+
     if ns.converters:
         if dry_run:
             parser.error("can't use --dry-run or --diff with --converters")
@@ -280,20 +318,22 @@ def run_clinic(parser: argparse.ArgumentParser, ns: argparse.Namespace) -> None:
         builtin_legacy_converters = dict(legacy_converters)
         builtin_return_converters = dict(return_converters)
 
-    writer = libclinic.FileWriter(dry_run=dry_run or ns.converters)
+    writer = libclinic.FileWriter(dry_run=dry_run or ns.converters or ns.list)
     for filename in filenames:
         if ns.verbose:
             print(filename, file=verbose_file)
-        parse_file(filename, output=ns.output,
-                   verify=not ns.force, limited_capi=ns.limited_capi,
-                   writer=writer)
+        clinic = parse_file(filename, output=ns.output,
+                            verify=not ns.force, limited_capi=ns.limited_capi,
+                            writer=writer)
+        if ns.list and clinic is not None:
+            print_definitions(clinic)
 
     if ns.converters:
         print_converters(
             defined_in_files(converters, builtin_converters),
             defined_in_files(legacy_converters, builtin_legacy_converters),
             defined_in_files(return_converters, builtin_return_converters))
-    else:
+    elif not ns.list:
         report_changes(writer, diff=ns.diff)