Debian Codegraph @

Tools/clinic/libclinic/cli.py

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