gh-108494: AC: Document How to use the Limited C API

Remove also the --limited command line option. Now the limited C API
is only used if the source code contains "#define Py_LIMITED_API".

Author: vstinner

Doc/howto/clinic.rst

@@ -1905,6 +1905,17 @@ blocks embedded in Python files look slightly different.  They look like this:
     #/*[python checksum:...]*/
 
 
+How to use the Limited C API
+----------------------------
+
+If a C source code contains ``#define Py_LIMITED_API``, the generated C code
+will use the :ref:`Limited API <limited-c-api>` to parse arguments. Private
+functions are not used in this case and the code parsing arguments can be a
+less efficient depending on the parameters (types, number, etc.).
+
+.. versionadded:: 3.13
+
+
 .. _clinic-howto-override-signature:
 
 How to override the generated signature

Lib/test/test_clinic.py

@@ -692,7 +692,7 @@ def expect_parsing_failure(
     ):
         errmsg = re.escape(dedent(expected_error).strip())
         with self.assertRaisesRegex(clinic.ClinicError, errmsg):
-            clinic.parse_file(filename, limited_capi=False)
+            clinic.parse_file(filename)
 
     def test_parse_file_no_extension(self) -> None:
         self.expect_parsing_failure(

Tools/clinic/clinic.py

@@ -2611,7 +2611,6 @@ def __repr__(self) -> str:
 def parse_file(
         filename: str,
         *,
-        limited_capi: bool,
         output: str | None = None,
         verify: bool = True,
 ) -> None:
@@ -2635,8 +2634,9 @@ def parse_file(
     if not find_start_re.search(raw):
         return
 
-    if LIMITED_CAPI_REGEX.search(raw):
-        limited_capi = True
+    # Use the limited C API if "#define Py_LIMITED_API" in found
+    # in the source code
+    limited_capi = bool(LIMITED_CAPI_REGEX.search(raw))
 
     assert isinstance(language, CLanguage)
     clinic = Clinic(language,
@@ -6096,8 +6096,6 @@ def create_cli() -> argparse.ArgumentParser:
     cmdline.add_argument("--exclude", type=str, action="append",
                          help=("a file to exclude in --make mode; "
                                "can be given multiple times"))
-    cmdline.add_argument("--limited", dest="limited_capi", action='store_true',
-                         help="use the Limited C API")
     cmdline.add_argument("filename", metavar="FILE", type=str, nargs="*",
                          help="the list of files to process")
     return cmdline
@@ -6188,8 +6186,7 @@ def run_clinic(parser: argparse.ArgumentParser, ns: argparse.Namespace) -> None:
                     continue
                 if ns.verbose:
                     print(path)
-                parse_file(path,
-                           verify=not ns.force, limited_capi=ns.limited_capi)
+                parse_file(path, verify=not ns.force)
         return
 
     if not ns.filename:
@@ -6201,8 +6198,7 @@ def run_clinic(parser: argparse.ArgumentParser, ns: argparse.Namespace) -> None:
     for filename in ns.filename:
         if ns.verbose:
             print(filename)
-        parse_file(filename, output=ns.output,
-                   verify=not ns.force, limited_capi=ns.limited_capi)
+        parse_file(filename, output=ns.output, verify=not ns.force)
 
 
 def main(argv: list[str] | None = None) -> NoReturn: