gh-104683: Add --exclude option to Argument Clinic CLI (#107770)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

Doc/howto/clinic.rst

@@ -188,6 +188,11 @@ The CLI supports the following options:
 
    The directory tree to walk in :option:`--make` mode.
 
+.. option:: --exclude EXCLUDE
+
+   A file to exclude in :option:`--make` mode.
+   This option can be given multiple times.
+
 .. option:: FILE ...
 
    The list of files to process.

Lib/test/test_clinic.py

@@ -2216,6 +2216,35 @@ def create_files(files, srcdir, code):
                     path = os.path.join(ext_path, filename)
                     self.assertNotIn(path, out)
 
+    def test_cli_make_exclude(self):
+        code = dedent("""
+            /*[clinic input]
+            [clinic start generated code]*/
+        """)
+        with os_helper.temp_dir(quiet=False) as tmp_dir:
+            # add some folders, some C files and a Python file
+            for fn in "file1.c", "file2.c", "file3.c", "file4.c":
+                path = os.path.join(tmp_dir, fn)
+                with open(path, "w", encoding="utf-8") as f:
+                    f.write(code)
+
+            # Run clinic in verbose mode with --make on tmpdir.
+            # Exclude file2.c and file3.c.
+            out = self.expect_success(
+                "-v", "--make", "--srcdir", tmp_dir,
+                "--exclude", os.path.join(tmp_dir, "file2.c"),
+                # The added ./ should be normalised away.
+                "--exclude", os.path.join(tmp_dir, "./file3.c"),
+                # Relative paths should also work.
+                "--exclude", "file4.c"
+            )
+
+            # expect verbose mode to only mention the C files in tmp_dir
+            self.assertIn("file1.c", out)
+            self.assertNotIn("file2.c", out)
+            self.assertNotIn("file3.c", out)
+            self.assertNotIn("file4.c", out)
+
     def test_cli_verbose(self):
         with os_helper.temp_dir() as tmp_dir:
             fn = os.path.join(tmp_dir, "test.c")

Makefile.pre.in

@@ -775,9 +775,13 @@ coverage-report: regen-token regen-frozen
 # Run "Argument Clinic" over all source files
 .PHONY: clinic
 clinic: check-clean-src $(srcdir)/Modules/_blake2/blake2s_impl.c
-	$(PYTHON_FOR_REGEN) $(srcdir)/Tools/clinic/clinic.py --make --srcdir $(srcdir)
+	$(PYTHON_FOR_REGEN) $(srcdir)/Tools/clinic/clinic.py --make --exclude Lib/test/clinic.test.c --srcdir $(srcdir)
 	$(PYTHON_FOR_REGEN) $(srcdir)/Tools/build/generate_global_objects.py
 
+.PHONY: clinic-tests
+clinic-tests: check-clean-src $(srcdir)/Lib/test/clinic.test.c
+	$(PYTHON_FOR_REGEN) $(srcdir)/Tools/clinic/clinic.py -f $(srcdir)/Lib/test/clinic.test.c
+
 # Build the interpreter
 $(BUILDPYTHON):	Programs/python.o $(LINK_PYTHON_DEPS)
 	$(LINKCC) $(PY_CORE_LDFLAGS) $(LINKFORSHARED) -o $@ Programs/python.o $(LINK_PYTHON_OBJS) $(LIBS) $(MODLIBS) $(SYSLIBS)

Misc/NEWS.d/next/Tools-Demos/2023-08-08-12-21-41.gh-issue-104683.DRsAQE.rst

@@ -0,0 +1 @@
+Add ``--exclude`` option to Argument Clinic CLI.

Tools/clinic/clinic.py

@@ -5834,6 +5834,9 @@ def create_cli() -> argparse.ArgumentParser:
                          help="walk --srcdir to run over all relevant files")
     cmdline.add_argument("--srcdir", type=str, default=os.curdir,
                          help="the directory tree to walk in --make mode")
+    cmdline.add_argument("--exclude", type=str, action="append",
+                         help=("a file to exclude in --make mode; "
+                               "can be given multiple times"))
     cmdline.add_argument("filename", metavar="FILE", type=str, nargs="*",
                          help="the list of files to process")
     return cmdline
@@ -5905,6 +5908,11 @@ def run_clinic(parser: argparse.ArgumentParser, ns: argparse.Namespace) -> None:
             parser.error("can't use -o or filenames with --make")
         if not ns.srcdir:
             parser.error("--srcdir must not be empty with --make")
+        if ns.exclude:
+            excludes = [os.path.join(ns.srcdir, f) for f in ns.exclude]
+            excludes = [os.path.normpath(f) for f in excludes]
+        else:
+            excludes = []
         for root, dirs, files in os.walk(ns.srcdir):
             for rcs_dir in ('.svn', '.git', '.hg', 'build', 'externals'):
                 if rcs_dir in dirs:
@@ -5914,6 +5922,9 @@ def run_clinic(parser: argparse.ArgumentParser, ns: argparse.Namespace) -> None:
                 if not filename.endswith(('.c', '.cpp', '.h')):
                     continue
                 path = os.path.join(root, filename)
+                path = os.path.normpath(path)
+                if path in excludes:
+                    continue
                 if ns.verbose:
                     print(path)
                 parse_file(path, verify=not ns.force)