Debian Codegraph @

Tools/clinic/libclinic/clanguage.py

raw
1 from __future__ import annotations
2 import itertools
3 import textwrap
4 from typing import TYPE_CHECKING, Literal, Final
5 from operator import attrgetter
6 from collections.abc import Iterable
7
8 import libclinic.cpp
9 from libclinic import (
10 unspecified, fail, Sentinels, VersionTuple)
11 from libclinic.codegen import CRenderData, TemplateDict, CodeGen
12 from libclinic.language import Language
13 from libclinic.function import (
14 Module, Class, Function, Parameter, ParamTuple,
15 permute_optional_groups,
16 GETTER, SETTER, METHOD_INIT)
17 from libclinic.converters import self_converter
18 from libclinic.parse_args import ParseArgsCodeGen
19 if TYPE_CHECKING:
20 from libclinic.app import Clinic
21
22
23 def count_required(subset: ParamTuple) -> int:
24 """Return the number of arguments which cannot be omitted.
25
26 A parameter in an optional group is passed together with its group,
27 so only trailing parameters with a default value can be omitted.
28 """
29 count = len(subset)
30 for p in reversed(subset):
31 if p.group or not p.is_optional():
32 break
33 count -= 1
34 return count
35
36
37 def c_id(name: str) -> str:
38 if len(name) == 1 and ord(name) < 256:
39 if name.isalnum():
40 return f"_Py_LATIN1_CHR('{name}')"
41 else:
42 return f'_Py_LATIN1_CHR({ord(name)})'
43 else:
44 return f'&_Py_ID({name})'
45
46
47 class CLanguage(Language):
48
49 body_prefix = "#"
50 language = 'C'
51 start_line = "/*[{dsl_name} input]"
52 body_prefix = ""
53 stop_line = "[{dsl_name} start generated code]*/"
54 checksum_line = "/*[{dsl_name} end generated code: {arguments}]*/"
55
56 COMPILER_DEPRECATION_WARNING_PROTOTYPE: Final[str] = r"""
57 // Emit compiler warnings when we get to Python {major}.{minor}.
58 #if PY_VERSION_HEX >= 0x{major:02x}{minor:02x}00C0
59 # error {message}
60 #elif PY_VERSION_HEX >= 0x{major:02x}{minor:02x}00A0
61 # ifdef _MSC_VER
62 # pragma message ({message})
63 # else
64 # warning {message}
65 # endif
66 #endif
67 """
68 DEPRECATION_WARNING_PROTOTYPE: Final[str] = r"""
69 if ({condition}) {{{{{errcheck}
70 if (PyErr_WarnEx(PyExc_DeprecationWarning,
71 {message}, 1))
72 {{{{
73 goto exit;
74 }}}}
75 }}}}
76 """
77
78 def __init__(self, filename: str) -> None:
79 super().__init__(filename)
80 self.cpp = libclinic.cpp.Monitor(filename)
81
82 def parse_line(self, line: str) -> None:
83 self.cpp.writeline(line)
84
85 def render(
86 self,
87 clinic: Clinic,
88 signatures: Iterable[Module | Class | Function]
89 ) -> str:
90 function = None
91 for o in signatures:
92 if isinstance(o, Function):
93 if function:
94 fail("You may specify at most one function per block.\nFound a block containing at least two:\n\t" + repr(function) + " and " + repr(o))
95 function = o
96 return self.render_function(clinic, function)
97
98 def compiler_deprecated_warning(
99 self,
100 func: Function,
101 parameters: list[Parameter],
102 ) -> str | None:
103 minversion: VersionTuple | None = None
104 for p in parameters:
105 for version in p.deprecated_positional, p.deprecated_keyword:
106 if version and (not minversion or minversion > version):
107 minversion = version
108 if not minversion:
109 return None
110
111 # Format the preprocessor warning and error messages.
112 assert isinstance(self.cpp.filename, str)
113 message = f"Update the clinic input of {func.full_name!r}."
114 code = self.COMPILER_DEPRECATION_WARNING_PROTOTYPE.format(
115 major=minversion[0],
116 minor=minversion[1],
117 message=libclinic.c_repr(message),
118 )
119 return libclinic.normalize_snippet(code)
120
121 def deprecate_positional_use(
122 self,
123 func: Function,
124 params: dict[int, Parameter],
125 ) -> str:
126 assert len(params) > 0
127 first_pos = next(iter(params))
128 last_pos = next(reversed(params))
129
130 # Format the deprecation message.
131 if len(params) == 1:
132 condition = f"nargs == {first_pos+1}"
133 amount = f"{first_pos+1} " if first_pos else ""
134 pl = "s"
135 else:
136 condition = f"nargs > {first_pos} && nargs <= {last_pos+1}"
137 amount = f"more than {first_pos} " if first_pos else ""
138 pl = "s" if first_pos != 1 else ""
139 message = (
140 f"Passing {amount}positional argument{pl} to "
141 f"{func.fulldisplayname}() is deprecated."
142 )
143
144 for (major, minor), group in itertools.groupby(
145 params.values(), key=attrgetter("deprecated_positional")
146 ):
147 names = [repr(p.name) for p in group]
148 pstr = libclinic.pprint_words(names)
149 if len(names) == 1:
150 message += (
151 f" Parameter {pstr} will become a keyword-only parameter "
152 f"in Python {major}.{minor}."
153 )
154 else:
155 message += (
156 f" Parameters {pstr} will become keyword-only parameters "
157 f"in Python {major}.{minor}."
158 )
159
160 # Append deprecation warning to docstring.
161 docstring = textwrap.fill(f"Note: {message}")
162 func.docstring += f"\n\n{docstring}\n"
163 # Format and return the code block.
164 code = self.DEPRECATION_WARNING_PROTOTYPE.format(
165 condition=condition,
166 errcheck="",
167 message=libclinic.wrapped_c_string_literal(message, width=64,
168 subsequent_indent=20),
169 )
170 return libclinic.normalize_snippet(code, indent=4)
171
172 def deprecate_keyword_use(
173 self,
174 func: Function,
175 params: dict[int, Parameter],
176 argname_fmt: str | None = None,
177 *,
178 fastcall: bool,
179 codegen: CodeGen,
180 ) -> str:
181 assert len(params) > 0
182 last_param = next(reversed(params.values()))
183 limited_capi = codegen.limited_capi
184
185 # Format the deprecation message.
186 containscheck = ""
187 conditions = []
188 for i, p in params.items():
189 if p.is_optional():
190 if argname_fmt:
191 conditions.append(f"nargs < {i+1} && {argname_fmt % i}")
192 elif fastcall:
193 conditions.append(f"nargs < {i+1} && PySequence_Contains(kwnames, {c_id(p.name)})")
194 containscheck = "PySequence_Contains"
195 codegen.add_include('pycore_runtime.h', '_Py_ID()')
196 else:
197 conditions.append(f"nargs < {i+1} && PyDict_Contains(kwargs, {c_id(p.name)})")
198 containscheck = "PyDict_Contains"
199 codegen.add_include('pycore_runtime.h', '_Py_ID()')
200 else:
201 conditions = [f"nargs < {i+1}"]
202 condition = ") || (".join(conditions)
203 if len(conditions) > 1:
204 condition = f"(({condition}))"
205 if last_param.is_optional():
206 if fastcall:
207 if limited_capi:
208 condition = f"kwnames && PyTuple_Size(kwnames) && {condition}"
209 else:
210 condition = f"kwnames && PyTuple_GET_SIZE(kwnames) && {condition}"
211 else:
212 if limited_capi:
213 condition = f"kwargs && PyDict_Size(kwargs) && {condition}"
214 else:
215 condition = f"kwargs && PyDict_GET_SIZE(kwargs) && {condition}"
216 names = [repr(p.name) for p in params.values()]
217 pstr = libclinic.pprint_words(names)
218 pl = 's' if len(params) != 1 else ''
219 message = (
220 f"Passing keyword argument{pl} {pstr} to "
221 f"{func.fulldisplayname}() is deprecated."
222 )
223
224 for (major, minor), group in itertools.groupby(
225 params.values(), key=attrgetter("deprecated_keyword")
226 ):
227 names = [repr(p.name) for p in group]
228 pstr = libclinic.pprint_words(names)
229 pl = 's' if len(names) != 1 else ''
230 message += (
231 f" Parameter{pl} {pstr} will become positional-only "
232 f"in Python {major}.{minor}."
233 )
234
235 if containscheck:
236 errcheck = f"""
237 if (PyErr_Occurred()) {{{{ // {containscheck}() above can fail
238 goto exit;
239 }}}}"""
240 else:
241 errcheck = ""
242 if argname_fmt:
243 # Append deprecation warning to docstring.
244 docstring = textwrap.fill(f"Note: {message}")
245 func.docstring += f"\n\n{docstring}\n"
246 # Format and return the code block.
247 code = self.DEPRECATION_WARNING_PROTOTYPE.format(
248 condition=condition,
249 errcheck=errcheck,
250 message=libclinic.wrapped_c_string_literal(message, width=64,
251 subsequent_indent=20),
252 )
253 return libclinic.normalize_snippet(code, indent=4)
254
255 def output_templates(
256 self,
257 f: Function,
258 codegen: CodeGen,
259 ) -> dict[str, str]:
260 args = ParseArgsCodeGen(f, codegen)
261 return args.parse_args(self)
262
263 @staticmethod
264 def group_to_variable_name(group: int) -> str:
265 adjective = "left_" if group < 0 else "right_"
266 return "group_" + adjective + str(abs(group))
267
268 def render_option_group_parsing(
269 self,
270 f: Function,
271 template_dict: TemplateDict,
272 limited_capi: bool,
273 ) -> None:
274 # positional only, grouped, optional arguments!
275 # can be optional on the left or right.
276 # here's an example:
277 #
278 # [ [ [ A1 A2 ] B1 B2 B3 ] C1 C2 ] D1 D2 D3 [ E1 E2 E3 [ F1 F2 F3 ] ]
279 #
280 # Here group D are required, and all other groups are optional.
281 # (Group D's "group" is actually None.)
282 # We can figure out which sets of arguments we have based on
283 # how many arguments are in the tuple.
284 #
285 # Note that you need to count up on both sides. For example,
286 # you could have groups C+D, or C+D+E, or C+D+E+F.
287 #
288 # What if the number of arguments leads us to an ambiguous result?
289 # Clinic prefers groups on the left. So in the above example,
290 # five arguments would map to B+C, not C+D.
291
292 out = []
293 parameters = list(f.parameters.values())
294 if isinstance(parameters[0].converter, self_converter):
295 del parameters[0]
296
297 group: list[Parameter] | None = None
298 left = []
299 right = []
300 required: list[Parameter] = []
301 last: int | Literal[Sentinels.unspecified] = unspecified
302
303 for p in parameters:
304 group_id = p.group
305 if group_id != last:
306 last = group_id
307 group = []
308 if group_id < 0:
309 left.append(group)
310 elif group_id == 0:
311 group = required
312 else:
313 right.append(group)
314 assert group is not None
315 group.append(p)
316
317 # Map the number of arguments to the subset which accepts it.
318 subsets: dict[int, ParamTuple] = {}
319 for subset in permute_optional_groups(left, required, right):
320 for count in range(count_required(subset), len(subset) + 1):
321 if count in subsets:
322 fail(f"Function {f.full_name!r} has an ambiguous group "
323 f"configuration: a call with {count} argument(s) "
324 f"can be parsed in more than one way.")
325 subsets[count] = subset
326
327 if limited_capi:
328 nargs = 'PyTuple_Size(args)'
329 else:
330 nargs = 'PyTuple_GET_SIZE(args)'
331 out.append(f"switch ({nargs}) {{\n")
332 for count, subset in sorted(subsets.items()):
333 if count < len(subset):
334 # The omitted parameters are parsed by the following case.
335 out.append(f" case {count}:\n")
336 continue
337
338 if count == 0:
339 out.append(""" case 0:
340 break;
341 """)
342 continue
343
344 # A set would eliminate duplicates too, but the iteration
345 # order of small negative integers depends on the platform.
346 group_ids = dict.fromkeys(p.group for p in subset)
347 d: dict[str, str | int] = {}
348 d['count'] = count
349 d['name'] = f.name
350 format_units = [p.converter.format_unit for p in subset]
351 n_required = count_required(subset)
352 if n_required < count:
353 format_units.insert(n_required, '|')
354 d['format_units'] = "".join(format_units)
355
356 parse_arguments: list[str] = []
357 for p in subset:
358 p.converter.parse_argument(parse_arguments)
359 d['parse_arguments'] = ", ".join(parse_arguments)
360
361 group_ids.pop(0, None)
362 lines = "\n".join([
363 self.group_to_variable_name(g) + " = 1;"
364 for g in group_ids
365 ])
366
367 s = """\
368 case {count}:
369 if (!PyArg_ParseTuple(args, "{format_units}:{name}", {parse_arguments})) {{
370 goto exit;
371 }}
372 {group_booleans}
373 break;
374 """
375 s = libclinic.linear_format(s, group_booleans=lines)
376 s = s.format_map(d)
377 out.append(s)
378
379 out.append(" default:\n")
380 s = ' PyErr_SetString(PyExc_TypeError, "{} requires {} to {} arguments");\n'
381 out.append(s.format(f.full_name, min(subsets), max(subsets)))
382 out.append(' goto exit;\n')
383 out.append("}")
384
385 template_dict['option_group_parsing'] = libclinic.format_escape("".join(out))
386
387 def render_function(
388 self,
389 clinic: Clinic,
390 f: Function | None
391 ) -> str:
392 if f is None:
393 return ""
394
395 codegen = clinic.codegen
396 data = CRenderData()
397
398 assert f.parameters, "We should always have a 'self' at this point!"
399 parameters = f.render_parameters
400 converters = [p.converter for p in parameters]
401
402 templates = self.output_templates(f, codegen)
403
404 f_self = parameters[0]
405 selfless = parameters[1:]
406 assert isinstance(f_self.converter, self_converter), "No self parameter in " + repr(f.full_name) + "!"
407
408 if f.critical_section:
409 match len(f.target_critical_section):
410 case 0:
411 lock = 'Py_BEGIN_CRITICAL_SECTION({self_name});'
412 unlock = 'Py_END_CRITICAL_SECTION();'
413 case 1:
414 lock = 'Py_BEGIN_CRITICAL_SECTION({target_critical_section});'
415 unlock = 'Py_END_CRITICAL_SECTION();'
416 case _:
417 lock = 'Py_BEGIN_CRITICAL_SECTION2({target_critical_section});'
418 unlock = 'Py_END_CRITICAL_SECTION2();'
419 data.lock.append(lock)
420 data.unlock.append(unlock)
421
422 last_group = 0
423 first_optional = len(selfless)
424 positional = selfless and selfless[-1].is_positional_only()
425 has_option_groups = False
426
427 # offset i by -1 because first_optional needs to ignore self
428 for i, p in enumerate(parameters, -1):
429 c = p.converter
430
431 if (i != -1) and (p.default is not unspecified):
432 first_optional = min(first_optional, i)
433
434 if p.is_vararg():
435 data.cleanup.append(f"Py_XDECREF({c.parser_name});")
436
437 # insert group variable
438 group = p.group
439 if last_group != group:
440 last_group = group
441 if group:
442 group_name = self.group_to_variable_name(group)
443 data.impl_arguments.append(group_name)
444 data.declarations.append("int " + group_name + " = 0;")
445 data.impl_parameters.append("int " + group_name)
446 has_option_groups = True
447
448 c.render(p, data)
449
450 if has_option_groups and (not positional):
451 fail("You cannot use optional groups ('[' and ']') "
452 "unless all parameters are positional-only ('/').")
453
454 # HACK
455 # when we're METH_O, but have a custom return converter,
456 # we use "impl_parameters" for the parsing function
457 # because that works better. but that means we must
458 # suppress actually declaring the impl's parameters
459 # as variables in the parsing function. but since it's
460 # METH_O, we have exactly one anyway, so we know exactly
461 # where it is.
462 if ("METH_O" in templates['methoddef_define'] and
463 '{impl_parameters}' in templates['parser_prototype']):
464 data.declarations.pop(0)
465
466 full_name = f.full_name
467 template_dict = {'full_name': full_name}
468 template_dict['name'] = f.displayname
469 if f.kind in {GETTER, SETTER}:
470 template_dict['getset_name'] = f.c_basename.upper()
471 template_dict['getset_basename'] = f.c_basename
472 if f.kind is GETTER:
473 template_dict['c_basename'] = f.c_basename + "_get"
474 elif f.kind is SETTER:
475 template_dict['c_basename'] = f.c_basename + "_set"
476 # Implicitly add the setter value parameter.
477 data.impl_parameters.append("PyObject *value")
478 data.impl_arguments.append("value")
479 else:
480 template_dict['methoddef_name'] = f.c_basename.upper() + "_METHODDEF"
481 template_dict['c_basename'] = f.c_basename
482
483 template_dict['docstring'] = libclinic.docstring_for_c_string(f.docstring)
484 template_dict['self_name'] = template_dict['self_type'] = template_dict['self_type_check'] = ''
485 template_dict['target_critical_section'] = ', '.join(f.target_critical_section)
486 for converter in converters:
487 converter.set_template_dict(template_dict)
488
489 if f.kind not in {SETTER, METHOD_INIT}:
490 f.return_converter.render(f, data)
491 template_dict['impl_return_type'] = f.return_converter.type
492
493 template_dict['declarations'] = libclinic.format_escape("\n".join(data.declarations))
494 template_dict['initializers'] = "\n\n".join(data.initializers)
495 template_dict['modifications'] = '\n\n'.join(data.modifications)
496 template_dict['keywords_c'] = ' '.join('"' + k + '",'
497 for k in data.keywords)
498 keywords = [k for k in data.keywords if k]
499 template_dict['keywords_py'] = ' '.join(c_id(k) + ','
500 for k in keywords)
501 template_dict['format_units'] = ''.join(data.format_units)
502 template_dict['parse_arguments'] = ', '.join(data.parse_arguments)
503 if data.parse_arguments:
504 template_dict['parse_arguments_comma'] = ',';
505 else:
506 template_dict['parse_arguments_comma'] = '';
507 template_dict['impl_parameters'] = ", ".join(data.impl_parameters)
508 template_dict['impl_arguments'] = ", ".join(data.impl_arguments)
509
510 template_dict['return_conversion'] = libclinic.format_escape("".join(data.return_conversion).rstrip())
511 template_dict['post_parsing'] = libclinic.format_escape("".join(data.post_parsing).rstrip())
512 template_dict['cleanup'] = libclinic.format_escape("".join(data.cleanup))
513
514 template_dict['return_value'] = data.return_value
515 template_dict['lock'] = "\n".join(data.lock)
516 template_dict['unlock'] = "\n".join(data.unlock)
517
518 # used by unpack tuple code generator
519 unpack_min = first_optional
520 unpack_max = len(selfless)
521 template_dict['unpack_min'] = str(unpack_min)
522 template_dict['unpack_max'] = str(unpack_max)
523
524 if has_option_groups:
525 self.render_option_group_parsing(f, template_dict,
526 limited_capi=codegen.limited_capi)
527
528 # buffers, not destination
529 for name, destination in clinic.destination_buffers.items():
530 template = templates[name]
531 if has_option_groups:
532 template = libclinic.linear_format(template,
533 option_group_parsing=template_dict['option_group_parsing'])
534 template = libclinic.linear_format(template,
535 declarations=template_dict['declarations'],
536 return_conversion=template_dict['return_conversion'],
537 initializers=template_dict['initializers'],
538 modifications=template_dict['modifications'],
539 post_parsing=template_dict['post_parsing'],
540 cleanup=template_dict['cleanup'],
541 lock=template_dict['lock'],
542 unlock=template_dict['unlock'],
543 )
544
545 # Only generate the "exit:" label
546 # if we have any gotos
547 label = "exit:" if "goto exit;" in template else ""
548 template = libclinic.linear_format(template, exit_label=label)
549
550 s = template.format_map(template_dict)
551
552 # mild hack:
553 # reflow long impl declarations
554 if name in {"impl_prototype", "impl_definition"}:
555 s = libclinic.wrap_declarations(s)
556
557 if clinic.line_prefix:
558 s = libclinic.indent_all_lines(s, clinic.line_prefix)
559 if clinic.line_suffix:
560 s = libclinic.suffix_all_lines(s, clinic.line_suffix)
561
562 destination.append(s)
563
564 return clinic.get_destination('block').dump()