Debian Codegraph @

Tools/clinic/libclinic/cli.py

raw
1 from __future__ import annotations
2
3 import argparse
4 import inspect
5 import os
6 import re
7 import sys
8 from collections.abc import Callable
9 from typing import NoReturn
10
11
12 # Local imports.
13 import libclinic
14 import libclinic.cpp
15 from libclinic import ClinicError
16 from libclinic.language import Language, PythonLanguage
17 from libclinic.block_parser import BlockParser
18 from libclinic.converter import (
19 ConverterType, converters, legacy_converters)
20 from libclinic.return_converters import (
21 return_converters, ReturnConverterType)
22 from libclinic.clanguage import CLanguage
23 from libclinic.app import Clinic
24
25
26 # TODO:
27 #
28 # soon:
29 #
30 # * allow mixing any two of {positional-only, positional-or-keyword,
31 # keyword-only}
32 # * dict constructor uses positional-only and keyword-only
33 # * max and min use positional only with an optional group
34 # and keyword-only
35 #
36
37
38 # Match '#define Py_LIMITED_API'.
39 # Match '# define Py_LIMITED_API 0x030d0000' (without the version).
40 LIMITED_CAPI_REGEX = re.compile(r'# *define +Py_LIMITED_API')
41
42
43 # "extensions" maps the file extension ("c", "py") to Language classes.
44 LangDict = dict[str, Callable[[str], Language]]
45 extensions: LangDict = { name: CLanguage for name in "c cc cpp cxx h hh hpp hxx".split() }
46 extensions['py'] = PythonLanguage
47
48
49 def parse_file(
50 filename: str,
51 *,
52 limited_capi: bool,
53 output: str | None = None,
54 verify: bool = True,
55 ) -> None:
56 if not output:
57 output = filename
58
59 extension = os.path.splitext(filename)[1][1:]
60 if not extension:
61 raise ClinicError(f"Can't extract file type for file {filename!r}")
62
63 try:
64 language = extensions[extension](filename)
65 except KeyError:
66 raise ClinicError(f"Can't identify file type for file {filename!r}")
67
68 with open(filename, encoding="utf-8") as f:
69 raw = f.read()
70
71 # exit quickly if there are no clinic markers in the file
72 find_start_re = BlockParser("", language).find_start_re
73 if not find_start_re.search(raw):
74 return
75
76 if LIMITED_CAPI_REGEX.search(raw):
77 limited_capi = True
78
79 assert isinstance(language, CLanguage)
80 clinic = Clinic(language,
81 verify=verify,
82 filename=filename,
83 limited_capi=limited_capi)
84 cooked = clinic.parse(raw)
85
86 libclinic.write_file(output, cooked)
87
88
89 def create_cli() -> argparse.ArgumentParser:
90 cmdline = argparse.ArgumentParser(
91 prog="clinic.py",
92 description="""Preprocessor for CPython C files.
93
94 The purpose of the Argument Clinic is automating all the boilerplate involved
95 with writing argument parsing code for builtins and providing introspection
96 signatures ("docstrings") for CPython builtins.
97
98 For more information see https://devguide.python.org/development-tools/clinic/""")
99 cmdline.add_argument("-f", "--force", action='store_true',
100 help="force output regeneration")
101 cmdline.add_argument("-o", "--output", type=str,
102 help="redirect file output to OUTPUT")
103 cmdline.add_argument("-v", "--verbose", action='store_true',
104 help="enable verbose mode")
105 cmdline.add_argument("--converters", action='store_true',
106 help=("print a list of all supported converters "
107 "and return converters"))
108 cmdline.add_argument("--make", action='store_true',
109 help="walk --srcdir to run over all relevant files")
110 cmdline.add_argument("--srcdir", type=str, default=os.curdir,
111 help="the directory tree to walk in --make mode")
112 cmdline.add_argument("--exclude", type=str, action="append",
113 help=("a file to exclude in --make mode; "
114 "can be given multiple times"))
115 cmdline.add_argument("--limited", dest="limited_capi", action='store_true',
116 help="use the Limited C API")
117 cmdline.add_argument("filename", metavar="FILE", type=str, nargs="*",
118 help="the list of files to process")
119 return cmdline
120
121
122 def run_clinic(parser: argparse.ArgumentParser, ns: argparse.Namespace) -> None:
123 if ns.converters:
124 if ns.filename:
125 parser.error(
126 "can't specify --converters and a filename at the same time"
127 )
128 AnyConverterType = ConverterType | ReturnConverterType
129 converter_list: list[tuple[str, AnyConverterType]] = []
130 return_converter_list: list[tuple[str, AnyConverterType]] = []
131
132 for name, converter in converters.items():
133 converter_list.append((
134 name,
135 converter,
136 ))
137 for name, return_converter in return_converters.items():
138 return_converter_list.append((
139 name,
140 return_converter
141 ))
142
143 print()
144
145 print("Legacy converters:")
146 legacy = sorted(legacy_converters)
147 print(' ' + ' '.join(c for c in legacy if c[0].isupper()))
148 print(' ' + ' '.join(c for c in legacy if c[0].islower()))
149 print()
150
151 for title, attribute, ids in (
152 ("Converters", 'converter_init', converter_list),
153 ("Return converters", 'return_converter_init', return_converter_list),
154 ):
155 print(title + ":")
156
157 ids.sort(key=lambda item: item[0].lower())
158 longest = -1
159 for name, _ in ids:
160 longest = max(longest, len(name))
161
162 for name, cls in ids:
163 callable = getattr(cls, attribute, None)
164 if not callable:
165 continue
166 signature = inspect.signature(callable)
167 parameters = []
168 for parameter_name, parameter in signature.parameters.items():
169 if parameter.kind == inspect.Parameter.KEYWORD_ONLY:
170 if parameter.default != inspect.Parameter.empty:
171 s = f'{parameter_name}={parameter.default!r}'
172 else:
173 s = parameter_name
174 parameters.append(s)
175 print(' {}({})'.format(name, ', '.join(parameters)))
176 print()
177 print("All converters also accept (c_default=None, py_default=None, annotation=None).")
178 print("All return converters also accept (py_default=None).")
179 return
180
181 if ns.make:
182 if ns.output or ns.filename:
183 parser.error("can't use -o or filenames with --make")
184 if not ns.srcdir:
185 parser.error("--srcdir must not be empty with --make")
186 if ns.exclude:
187 excludes = [os.path.join(ns.srcdir, f) for f in ns.exclude]
188 excludes = [os.path.normpath(f) for f in excludes]
189 else:
190 excludes = []
191 for root, dirs, files in os.walk(ns.srcdir):
192 for rcs_dir in ('.svn', '.git', '.hg', 'build', 'externals'):
193 if rcs_dir in dirs:
194 dirs.remove(rcs_dir)
195 for filename in files:
196 # handle .c, .cpp and .h files
197 if not filename.endswith(('.c', '.cpp', '.h')):
198 continue
199 path = os.path.join(root, filename)
200 path = os.path.normpath(path)
201 if path in excludes:
202 continue
203 if ns.verbose:
204 print(path)
205 parse_file(path,
206 verify=not ns.force, limited_capi=ns.limited_capi)
207 return
208
209 if not ns.filename:
210 parser.error("no input files")
211
212 if ns.output and len(ns.filename) > 1:
213 parser.error("can't use -o with multiple filenames")
214
215 for filename in ns.filename:
216 if ns.verbose:
217 print(filename)
218 parse_file(filename, output=ns.output,
219 verify=not ns.force, limited_capi=ns.limited_capi)
220
221
222 def main(argv: list[str] | None = None) -> NoReturn:
223 parser = create_cli()
224 args = parser.parse_args(argv)
225 try:
226 run_clinic(parser, args)
227 except ClinicError as exc:
228 sys.stderr.write(exc.report())
229 sys.exit(1)
230 else:
231 sys.exit(0)