Debian Codegraph @

Tools/clinic/libclinic/dsl_parser.py

raw
1 from __future__ import annotations
2 import ast
3 import enum
4 import inspect
5 import pprint
6 import re
7 import shlex
8 import sys
9 from collections.abc import Callable
10 from types import FunctionType, NoneType
11 from typing import TYPE_CHECKING, Any, NamedTuple
12
13 import libclinic
14 from libclinic import (
15 ClinicError, VersionTuple,
16 fail, warn, unspecified, unknown, NULL)
17 from libclinic.function import (
18 Module, Class, Function, Parameter,
19 FunctionKind,
20 CALLABLE, STATIC_METHOD, CLASS_METHOD, METHOD_INIT, METHOD_NEW,
21 GETTER, SETTER)
22 from libclinic.converter import (
23 converters, legacy_converters)
24 from libclinic.converters import (
25 self_converter, defining_class_converter,
26 correct_name_for_self)
27 from libclinic.return_converters import (
28 CReturnConverter, return_converters,
29 int_return_converter)
30 from libclinic.parser import create_parser_namespace
31 if TYPE_CHECKING:
32 from libclinic.block_parser import Block
33 from libclinic.app import Clinic
34
35
36 unsupported_special_methods: set[str] = set("""
37
38 __abs__
39 __add__
40 __and__
41 __call__
42 __delitem__
43 __divmod__
44 __eq__
45 __float__
46 __floordiv__
47 __ge__
48 __getattr__
49 __getattribute__
50 __getitem__
51 __gt__
52 __hash__
53 __iadd__
54 __iand__
55 __ifloordiv__
56 __ilshift__
57 __imatmul__
58 __imod__
59 __imul__
60 __index__
61 __int__
62 __invert__
63 __ior__
64 __ipow__
65 __irshift__
66 __isub__
67 __iter__
68 __itruediv__
69 __ixor__
70 __le__
71 __len__
72 __lshift__
73 __lt__
74 __matmul__
75 __mod__
76 __mul__
77 __neg__
78 __next__
79 __or__
80 __pos__
81 __pow__
82 __radd__
83 __rand__
84 __rdivmod__
85 __repr__
86 __rfloordiv__
87 __rlshift__
88 __rmatmul__
89 __rmod__
90 __rmul__
91 __ror__
92 __rpow__
93 __rrshift__
94 __rshift__
95 __rsub__
96 __rtruediv__
97 __rxor__
98 __setattr__
99 __setitem__
100 __str__
101 __sub__
102 __truediv__
103 __xor__
104
105 """.strip().split())
106
107
108 StateKeeper = Callable[[str], None]
109 ConverterArgs = dict[str, Any]
110
111
112 class ParamState(enum.IntEnum):
113 """Parameter parsing state.
114
115 [ [ a, b, ] c, ] d, e, f=3, [ g, h, [ i ] ] <- line
116 01 2 3 4 5 6 <- state transitions
117 """
118 # Before we've seen anything.
119 # Legal transitions: to LEFT_SQUARE_BEFORE or REQUIRED
120 START = 0
121
122 # Left square backets before required params.
123 LEFT_SQUARE_BEFORE = 1
124
125 # In a group, before required params.
126 GROUP_BEFORE = 2
127
128 # Required params, positional-or-keyword or positional-only (we
129 # don't know yet). Renumber left groups!
130 REQUIRED = 3
131
132 # Positional-or-keyword or positional-only params that now must have
133 # default values.
134 OPTIONAL = 4
135
136 # In a group, after required params.
137 GROUP_AFTER = 5
138
139 # Right square brackets after required params.
140 RIGHT_SQUARE_AFTER = 6
141
142
143 class FunctionNames(NamedTuple):
144 full_name: str
145 c_basename: str
146
147
148 def eval_ast_expr(
149 node: ast.expr,
150 *,
151 filename: str = '-'
152 ) -> Any:
153 """
154 Takes an ast.Expr node. Compiles it into a function object,
155 then calls the function object with 0 arguments.
156 Returns the result of that function call.
157
158 globals represents the globals dict the expression
159 should see. (There's no equivalent for "locals" here.)
160 """
161
162 if isinstance(node, ast.Expr):
163 node = node.value
164
165 expr = ast.Expression(node)
166 namespace = create_parser_namespace()
167 co = compile(expr, filename, 'eval')
168 fn = FunctionType(co, namespace)
169 return fn()
170
171
172 class IndentStack:
173 def __init__(self) -> None:
174 self.indents: list[int] = []
175 self.margin: str | None = None
176
177 def _ensure(self) -> None:
178 if not self.indents:
179 fail('IndentStack expected indents, but none are defined.')
180
181 def measure(self, line: str) -> int:
182 """
183 Returns the length of the line's margin.
184 """
185 if '\t' in line:
186 fail('Tab characters are illegal in the Argument Clinic DSL.')
187 stripped = line.lstrip()
188 if not len(stripped):
189 # we can't tell anything from an empty line
190 # so just pretend it's indented like our current indent
191 self._ensure()
192 return self.indents[-1]
193 return len(line) - len(stripped)
194
195 def infer(self, line: str) -> int:
196 """
197 Infer what is now the current margin based on this line.
198 Returns:
199 1 if we have indented (or this is the first margin)
200 0 if the margin has not changed
201 -N if we have dedented N times
202 """
203 indent = self.measure(line)
204 margin = ' ' * indent
205 if not self.indents:
206 self.indents.append(indent)
207 self.margin = margin
208 return 1
209 current = self.indents[-1]
210 if indent == current:
211 return 0
212 if indent > current:
213 self.indents.append(indent)
214 self.margin = margin
215 return 1
216 # indent < current
217 if indent not in self.indents:
218 fail("Illegal outdent.")
219 outdent_count = 0
220 while indent != current:
221 self.indents.pop()
222 current = self.indents[-1]
223 outdent_count -= 1
224 self.margin = margin
225 return outdent_count
226
227 @property
228 def depth(self) -> int:
229 """
230 Returns how many margins are currently defined.
231 """
232 return len(self.indents)
233
234 def dedent(self, line: str) -> str:
235 """
236 Dedents a line by the currently defined margin.
237 """
238 assert self.margin is not None, "Cannot call .dedent() before calling .infer()"
239 margin = self.margin
240 indent = self.indents[-1]
241 if not line.startswith(margin):
242 fail('Cannot dedent; line does not start with the previous margin.')
243 return line[indent:]
244
245
246 class DSLParser:
247 function: Function | None
248 state: StateKeeper
249 keyword_only: bool
250 positional_only: bool
251 deprecated_positional: VersionTuple | None
252 deprecated_keyword: VersionTuple | None
253 group: int
254 parameter_state: ParamState
255 indent: IndentStack
256 kind: FunctionKind
257 coexist: bool
258 forced_text_signature: str | None
259 parameter_continuation: str
260 preserve_output: bool
261 critical_section: bool
262 target_critical_section: list[str]
263 from_version_re = re.compile(r'([*/]) +\[from +(.+)\]')
264
265 def __init__(self, clinic: Clinic) -> None:
266 self.clinic = clinic
267
268 self.directives = {}
269 for name in dir(self):
270 # functions that start with directive_ are added to directives
271 _, s, key = name.partition("directive_")
272 if s:
273 self.directives[key] = getattr(self, name)
274
275 # functions that start with at_ are too, with an @ in front
276 _, s, key = name.partition("at_")
277 if s:
278 self.directives['@' + key] = getattr(self, name)
279
280 self.reset()
281
282 def reset(self) -> None:
283 self.function = None
284 self.state = self.state_dsl_start
285 self.keyword_only = False
286 self.positional_only = False
287 self.deprecated_positional = None
288 self.deprecated_keyword = None
289 self.group = 0
290 self.parameter_state: ParamState = ParamState.START
291 self.indent = IndentStack()
292 self.kind = CALLABLE
293 self.coexist = False
294 self.forced_text_signature = None
295 self.parameter_continuation = ''
296 self.preserve_output = False
297 self.critical_section = False
298 self.target_critical_section = []
299
300 def directive_module(self, name: str) -> None:
301 fields = name.split('.')[:-1]
302 module, cls = self.clinic._module_and_class(fields)
303 if cls:
304 fail("Can't nest a module inside a class!")
305
306 if name in module.modules:
307 fail(f"Already defined module {name!r}!")
308
309 m = Module(name, module)
310 module.modules[name] = m
311 self.block.signatures.append(m)
312
313 def directive_class(
314 self,
315 name: str,
316 typedef: str,
317 type_object: str
318 ) -> None:
319 fields = name.split('.')
320 name = fields.pop()
321 module, cls = self.clinic._module_and_class(fields)
322
323 parent = cls or module
324 if name in parent.classes:
325 fail(f"Already defined class {name!r}!")
326
327 c = Class(name, module, cls, typedef, type_object)
328 parent.classes[name] = c
329 self.block.signatures.append(c)
330
331 def directive_set(self, name: str, value: str) -> None:
332 if name not in ("line_prefix", "line_suffix"):
333 fail(f"unknown variable {name!r}")
334
335 value = value.format_map({
336 'block comment start': '/*',
337 'block comment end': '*/',
338 })
339
340 self.clinic.__dict__[name] = value
341
342 def directive_destination(
343 self,
344 name: str,
345 command: str,
346 *args: str
347 ) -> None:
348 match command:
349 case "new":
350 self.clinic.add_destination(name, *args)
351 case "clear":
352 self.clinic.get_destination(name).clear()
353 case _:
354 fail(f"unknown destination command {command!r}")
355
356
357 def directive_output(
358 self,
359 command_or_name: str,
360 destination: str = ''
361 ) -> None:
362 fd = self.clinic.destination_buffers
363
364 if command_or_name == "preset":
365 preset = self.clinic.presets.get(destination)
366 if not preset:
367 fail(f"Unknown preset {destination!r}!")
368 fd.update(preset)
369 return
370
371 if command_or_name == "push":
372 self.clinic.destination_buffers_stack.append(fd.copy())
373 return
374
375 if command_or_name == "pop":
376 if not self.clinic.destination_buffers_stack:
377 fail("Can't 'output pop', stack is empty!")
378 previous_fd = self.clinic.destination_buffers_stack.pop()
379 fd.update(previous_fd)
380 return
381
382 # secret command for debugging!
383 if command_or_name == "print":
384 self.block.output.append(pprint.pformat(fd))
385 self.block.output.append('\n')
386 return
387
388 d = self.clinic.get_destination_buffer(destination)
389
390 if command_or_name == "everything":
391 for name in list(fd):
392 fd[name] = d
393 return
394
395 if command_or_name not in fd:
396 allowed = ["preset", "push", "pop", "print", "everything"]
397 allowed.extend(fd)
398 fail(f"Invalid command or destination name {command_or_name!r}. "
399 "Must be one of:\n -",
400 "\n - ".join([repr(word) for word in allowed]))
401 fd[command_or_name] = d
402
403 def directive_dump(self, name: str) -> None:
404 self.block.output.append(self.clinic.get_destination(name).dump())
405
406 def directive_printout(self, *args: str) -> None:
407 self.block.output.append(' '.join(args))
408 self.block.output.append('\n')
409
410 def directive_preserve(self) -> None:
411 if self.preserve_output:
412 fail("Can't have 'preserve' twice in one block!")
413 self.preserve_output = True
414
415 def at_classmethod(self) -> None:
416 if self.kind is not CALLABLE:
417 fail("Can't set @classmethod, function is not a normal callable")
418 self.kind = CLASS_METHOD
419
420 def at_critical_section(self, *args: str) -> None:
421 if len(args) > 2:
422 fail("Up to 2 critical section variables are supported")
423 self.target_critical_section.extend(args)
424 self.critical_section = True
425
426 def at_getter(self) -> None:
427 match self.kind:
428 case FunctionKind.GETTER:
429 fail("Cannot apply @getter twice to the same function!")
430 case FunctionKind.SETTER:
431 fail("Cannot apply both @getter and @setter to the same function!")
432 case _:
433 self.kind = FunctionKind.GETTER
434
435 def at_setter(self) -> None:
436 match self.kind:
437 case FunctionKind.SETTER:
438 fail("Cannot apply @setter twice to the same function!")
439 case FunctionKind.GETTER:
440 fail("Cannot apply both @getter and @setter to the same function!")
441 case _:
442 self.kind = FunctionKind.SETTER
443
444 def at_staticmethod(self) -> None:
445 if self.kind is not CALLABLE:
446 fail("Can't set @staticmethod, function is not a normal callable")
447 self.kind = STATIC_METHOD
448
449 def at_coexist(self) -> None:
450 if self.coexist:
451 fail("Called @coexist twice!")
452 self.coexist = True
453
454 def at_text_signature(self, text_signature: str) -> None:
455 if self.forced_text_signature:
456 fail("Called @text_signature twice!")
457 self.forced_text_signature = text_signature
458
459 def parse(self, block: Block) -> None:
460 self.reset()
461 self.block = block
462 self.saved_output = self.block.output
463 block.output = []
464 block_start = self.clinic.block_parser.line_number
465 lines = block.input.split('\n')
466 for line_number, line in enumerate(lines, self.clinic.block_parser.block_start_line_number):
467 if '\t' in line:
468 fail(f'Tab characters are illegal in the Clinic DSL: {line!r}',
469 line_number=block_start)
470 try:
471 self.state(line)
472 except ClinicError as exc:
473 exc.lineno = line_number
474 exc.filename = self.clinic.filename
475 raise
476
477 self.do_post_block_processing_cleanup(line_number)
478 block.output.extend(self.clinic.language.render(self.clinic, block.signatures))
479
480 if self.preserve_output:
481 if block.output:
482 fail("'preserve' only works for blocks that don't produce any output!",
483 line_number=line_number)
484 block.output = self.saved_output
485
486 def in_docstring(self) -> bool:
487 """Return true if we are processing a docstring."""
488 return self.state in {
489 self.state_parameter_docstring,
490 self.state_function_docstring,
491 }
492
493 def valid_line(self, line: str) -> bool:
494 # ignore comment-only lines
495 if line.lstrip().startswith('#'):
496 return False
497
498 # Ignore empty lines too
499 # (but not in docstring sections!)
500 if not self.in_docstring() and not line.strip():
501 return False
502
503 return True
504
505 def next(
506 self,
507 state: StateKeeper,
508 line: str | None = None
509 ) -> None:
510 self.state = state
511 if line is not None:
512 self.state(line)
513
514 def state_dsl_start(self, line: str) -> None:
515 if not self.valid_line(line):
516 return
517
518 # is it a directive?
519 fields = shlex.split(line)
520 directive_name = fields[0]
521 directive = self.directives.get(directive_name, None)
522 if directive:
523 try:
524 directive(*fields[1:])
525 except TypeError as e:
526 fail(str(e))
527 return
528
529 self.next(self.state_modulename_name, line)
530
531 def parse_function_names(self, line: str) -> FunctionNames:
532 left, as_, right = line.partition(' as ')
533 full_name = left.strip()
534 c_basename = right.strip()
535 if as_ and not c_basename:
536 fail("No C basename provided after 'as' keyword")
537 if not c_basename:
538 fields = full_name.split(".")
539 if fields[-1] == '__new__':
540 fields.pop()
541 c_basename = "_".join(fields)
542 if not libclinic.is_legal_py_identifier(full_name):
543 fail(f"Illegal function name: {full_name!r}")
544 if not libclinic.is_legal_c_identifier(c_basename):
545 fail(f"Illegal C basename: {c_basename!r}")
546 names = FunctionNames(full_name=full_name, c_basename=c_basename)
547 self.normalize_function_kind(names.full_name)
548 return names
549
550 def normalize_function_kind(self, fullname: str) -> None:
551 # Fetch the method name and possibly class.
552 fields = fullname.split('.')
553 name = fields.pop()
554 _, cls = self.clinic._module_and_class(fields)
555
556 # Check special method requirements.
557 if name in unsupported_special_methods:
558 fail(f"{name!r} is a special method and cannot be converted to Argument Clinic!")
559 if name == '__init__' and (self.kind is not CALLABLE or not cls):
560 fail(f"{name!r} must be a normal method; got '{self.kind}'!")
561 if name == '__new__' and (self.kind is not CLASS_METHOD or not cls):
562 fail("'__new__' must be a class method!")
563 if self.kind in {GETTER, SETTER} and not cls:
564 fail("@getter and @setter must be methods")
565
566 # Normalise self.kind.
567 if name == '__new__':
568 self.kind = METHOD_NEW
569 elif name == '__init__':
570 self.kind = METHOD_INIT
571
572 def resolve_return_converter(
573 self, full_name: str, forced_converter: str
574 ) -> CReturnConverter:
575 if forced_converter:
576 if self.kind in {GETTER, SETTER}:
577 fail(f"@{self.kind.name.lower()} method cannot define a return type")
578 if self.kind is METHOD_INIT:
579 fail("__init__ methods cannot define a return type")
580 ast_input = f"def x() -> {forced_converter}: pass"
581 try:
582 module_node = ast.parse(ast_input)
583 except SyntaxError:
584 fail(f"Badly formed annotation for {full_name!r}: {forced_converter!r}")
585 function_node = module_node.body[0]
586 assert isinstance(function_node, ast.FunctionDef)
587 try:
588 name, legacy, kwargs = self.parse_converter(function_node.returns)
589 if legacy:
590 fail(f"Legacy converter {name!r} not allowed as a return converter")
591 if name not in return_converters:
592 fail(f"No available return converter called {name!r}")
593 return return_converters[name](**kwargs)
594 except ValueError:
595 fail(f"Badly formed annotation for {full_name!r}: {forced_converter!r}")
596
597 if self.kind in {METHOD_INIT, SETTER}:
598 return int_return_converter()
599 return CReturnConverter()
600
601 def parse_cloned_function(self, names: FunctionNames, existing: str) -> None:
602 full_name, c_basename = names
603 fields = [x.strip() for x in existing.split('.')]
604 function_name = fields.pop()
605 module, cls = self.clinic._module_and_class(fields)
606 parent = cls or module
607
608 for existing_function in parent.functions:
609 if existing_function.name == function_name:
610 break
611 else:
612 print(f"{cls=}, {module=}, {existing=}", file=sys.stderr)
613 print(f"{(cls or module).functions=}", file=sys.stderr)
614 fail(f"Couldn't find existing function {existing!r}!")
615
616 fields = [x.strip() for x in full_name.split('.')]
617 function_name = fields.pop()
618 module, cls = self.clinic._module_and_class(fields)
619
620 overrides: dict[str, Any] = {
621 "name": function_name,
622 "full_name": full_name,
623 "module": module,
624 "cls": cls,
625 "c_basename": c_basename,
626 "docstring": "",
627 }
628 if not (existing_function.kind is self.kind and
629 existing_function.coexist == self.coexist):
630 # Allow __new__ or __init__ methods.
631 if existing_function.kind.new_or_init:
632 overrides["kind"] = self.kind
633 # Future enhancement: allow custom return converters
634 overrides["return_converter"] = CReturnConverter()
635 else:
636 fail("'kind' of function and cloned function don't match! "
637 "(@classmethod/@staticmethod/@coexist)")
638 function = existing_function.copy(**overrides)
639 self.function = function
640 self.block.signatures.append(function)
641 (cls or module).functions.append(function)
642 self.next(self.state_function_docstring)
643
644 def state_modulename_name(self, line: str) -> None:
645 # looking for declaration, which establishes the leftmost column
646 # line should be
647 # modulename.fnname [as c_basename] [-> return annotation]
648 # square brackets denote optional syntax.
649 #
650 # alternatively:
651 # modulename.fnname [as c_basename] = modulename.existing_fn_name
652 # clones the parameters and return converter from that
653 # function. you can't modify them. you must enter a
654 # new docstring.
655 #
656 # (but we might find a directive first!)
657 #
658 # this line is permitted to start with whitespace.
659 # we'll call this number of spaces F (for "function").
660
661 assert self.valid_line(line)
662 self.indent.infer(line)
663
664 # are we cloning?
665 before, equals, existing = line.rpartition('=')
666 if equals:
667 existing = existing.strip()
668 if libclinic.is_legal_py_identifier(existing):
669 if self.forced_text_signature:
670 fail("Cannot use @text_signature when cloning a function")
671 # we're cloning!
672 names = self.parse_function_names(before)
673 return self.parse_cloned_function(names, existing)
674
675 line, _, returns = line.partition('->')
676 returns = returns.strip()
677 full_name, c_basename = self.parse_function_names(line)
678 return_converter = self.resolve_return_converter(full_name, returns)
679
680 fields = [x.strip() for x in full_name.split('.')]
681 function_name = fields.pop()
682 module, cls = self.clinic._module_and_class(fields)
683
684 func = Function(
685 name=function_name,
686 full_name=full_name,
687 module=module,
688 cls=cls,
689 c_basename=c_basename,
690 return_converter=return_converter,
691 kind=self.kind,
692 coexist=self.coexist,
693 critical_section=self.critical_section,
694 target_critical_section=self.target_critical_section,
695 forced_text_signature=self.forced_text_signature
696 )
697 self.add_function(func)
698
699 self.next(self.state_parameters_start)
700
701 def add_function(self, func: Function) -> None:
702 # Insert a self converter automatically.
703 tp, name = correct_name_for_self(func)
704 if func.cls and tp == "PyObject *":
705 func.self_converter = self_converter(name, name, func,
706 type=func.cls.typedef)
707 else:
708 func.self_converter = self_converter(name, name, func)
709 func.parameters[name] = Parameter(
710 name,
711 inspect.Parameter.POSITIONAL_ONLY,
712 function=func,
713 converter=func.self_converter
714 )
715
716 self.block.signatures.append(func)
717 self.function = func
718 (func.cls or func.module).functions.append(func)
719
720 # Now entering the parameters section. The rules, formally stated:
721 #
722 # * All lines must be indented with spaces only.
723 # * The first line must be a parameter declaration.
724 # * The first line must be indented.
725 # * This first line establishes the indent for parameters.
726 # * We'll call this number of spaces P (for "parameter").
727 # * Thenceforth:
728 # * Lines indented with P spaces specify a parameter.
729 # * Lines indented with > P spaces are docstrings for the previous
730 # parameter.
731 # * We'll call this number of spaces D (for "docstring").
732 # * All subsequent lines indented with >= D spaces are stored as
733 # part of the per-parameter docstring.
734 # * All lines will have the first D spaces of the indent stripped
735 # before they are stored.
736 # * It's illegal to have a line starting with a number of spaces X
737 # such that P < X < D.
738 # * A line with < P spaces is the first line of the function
739 # docstring, which ends processing for parameters and per-parameter
740 # docstrings.
741 # * The first line of the function docstring must be at the same
742 # indent as the function declaration.
743 # * It's illegal to have any line in the parameters section starting
744 # with X spaces such that F < X < P. (As before, F is the indent
745 # of the function declaration.)
746 #
747 # Also, currently Argument Clinic places the following restrictions on groups:
748 # * Each group must contain at least one parameter.
749 # * Each group may contain at most one group, which must be the furthest
750 # thing in the group from the required parameters. (The nested group
751 # must be the first in the group when it's before the required
752 # parameters, and the last thing in the group when after the required
753 # parameters.)
754 # * There may be at most one (top-level) group to the left or right of
755 # the required parameters.
756 # * You must specify a slash, and it must be after all parameters.
757 # (In other words: either all parameters are positional-only,
758 # or none are.)
759 #
760 # Said another way:
761 # * Each group must contain at least one parameter.
762 # * All left square brackets before the required parameters must be
763 # consecutive. (You can't have a left square bracket followed
764 # by a parameter, then another left square bracket. You can't
765 # have a left square bracket, a parameter, a right square bracket,
766 # and then a left square bracket.)
767 # * All right square brackets after the required parameters must be
768 # consecutive.
769 #
770 # These rules are enforced with a single state variable:
771 # "parameter_state". (Previously the code was a miasma of ifs and
772 # separate boolean state variables.) The states are defined in the
773 # ParamState class.
774
775 def state_parameters_start(self, line: str) -> None:
776 if not self.valid_line(line):
777 return
778
779 # if this line is not indented, we have no parameters
780 if not self.indent.infer(line):
781 return self.next(self.state_function_docstring, line)
782
783 assert self.function is not None
784 if self.function.kind in {GETTER, SETTER}:
785 getset = self.function.kind.name.lower()
786 fail(f"@{getset} methods cannot define parameters")
787
788 self.parameter_continuation = ''
789 return self.next(self.state_parameter, line)
790
791
792 def to_required(self) -> None:
793 """
794 Transition to the "required" parameter state.
795 """
796 if self.parameter_state is not ParamState.REQUIRED:
797 self.parameter_state = ParamState.REQUIRED
798 assert self.function is not None
799 for p in self.function.parameters.values():
800 p.group = -p.group
801
802 def state_parameter(self, line: str) -> None:
803 assert isinstance(self.function, Function)
804
805 if not self.valid_line(line):
806 return
807
808 if self.parameter_continuation:
809 line = self.parameter_continuation + ' ' + line.lstrip()
810 self.parameter_continuation = ''
811
812 assert self.indent.depth == 2
813 indent = self.indent.infer(line)
814 if indent == -1:
815 # we outdented, must be to definition column
816 return self.next(self.state_function_docstring, line)
817
818 if indent == 1:
819 # we indented, must be to new parameter docstring column
820 return self.next(self.state_parameter_docstring_start, line)
821
822 line = line.rstrip()
823 if line.endswith('\\'):
824 self.parameter_continuation = line[:-1]
825 return
826
827 line = line.lstrip()
828 version: VersionTuple | None = None
829 match = self.from_version_re.fullmatch(line)
830 if match:
831 line = match[1]
832 version = self.parse_version(match[2])
833
834 func = self.function
835 match line:
836 case '*':
837 self.parse_star(func, version)
838 case '[':
839 self.parse_opening_square_bracket(func)
840 case ']':
841 self.parse_closing_square_bracket(func)
842 case '/':
843 self.parse_slash(func, version)
844 case param:
845 self.parse_parameter(param)
846
847 def parse_parameter(self, line: str) -> None:
848 assert self.function is not None
849
850 match self.parameter_state:
851 case ParamState.START | ParamState.REQUIRED:
852 self.to_required()
853 case ParamState.LEFT_SQUARE_BEFORE:
854 self.parameter_state = ParamState.GROUP_BEFORE
855 case ParamState.GROUP_BEFORE:
856 if not self.group:
857 self.to_required()
858 case ParamState.GROUP_AFTER | ParamState.OPTIONAL:
859 pass
860 case st:
861 fail(f"Function {self.function.name} has an unsupported group configuration. (Unexpected state {st}.a)")
862
863 # handle "as" for parameters too
864 c_name = None
865 name, have_as_token, trailing = line.partition(' as ')
866 if have_as_token:
867 name = name.strip()
868 if ' ' not in name:
869 fields = trailing.strip().split(' ')
870 if not fields:
871 fail("Invalid 'as' clause!")
872 c_name = fields[0]
873 if c_name.endswith(':'):
874 name += ':'
875 c_name = c_name[:-1]
876 fields[0] = name
877 line = ' '.join(fields)
878
879 default: str | None
880 base, equals, default = line.rpartition('=')
881 if not equals:
882 base = default
883 default = None
884
885 module = None
886 try:
887 ast_input = f"def x({base}): pass"
888 module = ast.parse(ast_input)
889 except SyntaxError:
890 try:
891 # the last = was probably inside a function call, like
892 # c: int(accept={str})
893 # so assume there was no actual default value.
894 default = None
895 ast_input = f"def x({line}): pass"
896 module = ast.parse(ast_input)
897 except SyntaxError:
898 pass
899 if not module:
900 fail(f"Function {self.function.name!r} has an invalid parameter declaration:\n\t",
901 repr(line))
902
903 function = module.body[0]
904 assert isinstance(function, ast.FunctionDef)
905 function_args = function.args
906
907 if len(function_args.args) > 1:
908 fail(f"Function {self.function.name!r} has an "
909 f"invalid parameter declaration (comma?): {line!r}")
910 if function_args.defaults or function_args.kw_defaults:
911 fail(f"Function {self.function.name!r} has an "
912 f"invalid parameter declaration (default value?): {line!r}")
913 if function_args.kwarg:
914 fail(f"Function {self.function.name!r} has an "
915 f"invalid parameter declaration (**kwargs?): {line!r}")
916
917 if function_args.vararg:
918 self.check_previous_star()
919 self.check_remaining_star()
920 is_vararg = True
921 parameter = function_args.vararg
922 else:
923 is_vararg = False
924 parameter = function_args.args[0]
925
926 parameter_name = parameter.arg
927 name, legacy, kwargs = self.parse_converter(parameter.annotation)
928
929 value: object
930 if not default:
931 if self.parameter_state is ParamState.OPTIONAL:
932 fail(f"Can't have a parameter without a default ({parameter_name!r}) "
933 "after a parameter with a default!")
934 if is_vararg:
935 value = NULL
936 kwargs.setdefault('c_default', "NULL")
937 else:
938 value = unspecified
939 if 'py_default' in kwargs:
940 fail("You can't specify py_default without specifying a default value!")
941 else:
942 if is_vararg:
943 fail("Vararg can't take a default value!")
944
945 if self.parameter_state is ParamState.REQUIRED:
946 self.parameter_state = ParamState.OPTIONAL
947 default = default.strip()
948 bad = False
949 ast_input = f"x = {default}"
950 try:
951 module = ast.parse(ast_input)
952
953 if 'c_default' not in kwargs:
954 # we can only represent very simple data values in C.
955 # detect whether default is okay, via a denylist
956 # of disallowed ast nodes.
957 class DetectBadNodes(ast.NodeVisitor):
958 bad = False
959 def bad_node(self, node: ast.AST) -> None:
960 self.bad = True
961
962 # inline function call
963 visit_Call = bad_node
964 # inline if statement ("x = 3 if y else z")
965 visit_IfExp = bad_node
966
967 # comprehensions and generator expressions
968 visit_ListComp = visit_SetComp = bad_node
969 visit_DictComp = visit_GeneratorExp = bad_node
970
971 # literals for advanced types
972 visit_Dict = visit_Set = bad_node
973 visit_List = visit_Tuple = bad_node
974
975 # "starred": "a = [1, 2, 3]; *a"
976 visit_Starred = bad_node
977
978 denylist = DetectBadNodes()
979 denylist.visit(module)
980 bad = denylist.bad
981 else:
982 # if they specify a c_default, we can be more lenient about the default value.
983 # but at least make an attempt at ensuring it's a valid expression.
984 try:
985 value = eval(default)
986 except NameError:
987 pass # probably a named constant
988 except Exception as e:
989 fail("Malformed expression given as default value "
990 f"{default!r} caused {e!r}")
991 else:
992 if value is unspecified:
993 fail("'unspecified' is not a legal default value!")
994 if bad:
995 fail(f"Unsupported expression as default value: {default!r}")
996
997 assignment = module.body[0]
998 assert isinstance(assignment, ast.Assign)
999 expr = assignment.value
1000 # mild hack: explicitly support NULL as a default value
1001 c_default: str | None
1002 if isinstance(expr, ast.Name) and expr.id == 'NULL':
1003 value = NULL
1004 py_default = '<unrepresentable>'
1005 c_default = "NULL"
1006 elif (isinstance(expr, ast.BinOp) or
1007 (isinstance(expr, ast.UnaryOp) and
1008 not (isinstance(expr.operand, ast.Constant) and
1009 type(expr.operand.value) in {int, float, complex})
1010 )):
1011 c_default = kwargs.get("c_default")
1012 if not (isinstance(c_default, str) and c_default):
1013 fail(f"When you specify an expression ({default!r}) "
1014 f"as your default value, "
1015 f"you MUST specify a valid c_default.",
1016 ast.dump(expr))
1017 py_default = default
1018 value = unknown
1019 elif isinstance(expr, ast.Attribute):
1020 a = []
1021 n: ast.expr | ast.Attribute = expr
1022 while isinstance(n, ast.Attribute):
1023 a.append(n.attr)
1024 n = n.value
1025 if not isinstance(n, ast.Name):
1026 fail(f"Unsupported default value {default!r} "
1027 "(looked like a Python constant)")
1028 a.append(n.id)
1029 py_default = ".".join(reversed(a))
1030
1031 c_default = kwargs.get("c_default")
1032 if not (isinstance(c_default, str) and c_default):
1033 fail(f"When you specify a named constant ({py_default!r}) "
1034 "as your default value, "
1035 "you MUST specify a valid c_default.")
1036
1037 try:
1038 value = eval(py_default)
1039 except NameError:
1040 value = unknown
1041 else:
1042 value = ast.literal_eval(expr)
1043 py_default = repr(value)
1044 if isinstance(value, (bool, NoneType)):
1045 c_default = "Py_" + py_default
1046 elif isinstance(value, str):
1047 c_default = libclinic.c_repr(value)
1048 else:
1049 c_default = py_default
1050
1051 except SyntaxError as e:
1052 fail(f"Syntax error: {e.text!r}")
1053 except (ValueError, AttributeError):
1054 value = unknown
1055 c_default = kwargs.get("c_default")
1056 py_default = default
1057 if not (isinstance(c_default, str) and c_default):
1058 fail("When you specify a named constant "
1059 f"({py_default!r}) as your default value, "
1060 "you MUST specify a valid c_default.")
1061
1062 kwargs.setdefault('c_default', c_default)
1063 kwargs.setdefault('py_default', py_default)
1064
1065 dict = legacy_converters if legacy else converters
1066 legacy_str = "legacy " if legacy else ""
1067 if name not in dict:
1068 fail(f'{name!r} is not a valid {legacy_str}converter')
1069 # if you use a c_name for the parameter, we just give that name to the converter
1070 # but the parameter object gets the python name
1071 converter = dict[name](c_name or parameter_name, parameter_name, self.function, value, **kwargs)
1072
1073 kind: inspect._ParameterKind
1074 if is_vararg:
1075 kind = inspect.Parameter.VAR_POSITIONAL
1076 elif self.keyword_only:
1077 kind = inspect.Parameter.KEYWORD_ONLY
1078 else:
1079 kind = inspect.Parameter.POSITIONAL_OR_KEYWORD
1080
1081 if isinstance(converter, self_converter):
1082 if len(self.function.parameters) == 1:
1083 if self.parameter_state is not ParamState.REQUIRED:
1084 fail("A 'self' parameter cannot be marked optional.")
1085 if value is not unspecified:
1086 fail("A 'self' parameter cannot have a default value.")
1087 if self.group:
1088 fail("A 'self' parameter cannot be in an optional group.")
1089 kind = inspect.Parameter.POSITIONAL_ONLY
1090 self.parameter_state = ParamState.START
1091 self.function.parameters.clear()
1092 else:
1093 fail("A 'self' parameter, if specified, must be the "
1094 "very first thing in the parameter block.")
1095
1096 if isinstance(converter, defining_class_converter):
1097 _lp = len(self.function.parameters)
1098 if _lp == 1:
1099 if self.parameter_state is not ParamState.REQUIRED:
1100 fail("A 'defining_class' parameter cannot be marked optional.")
1101 if value is not unspecified:
1102 fail("A 'defining_class' parameter cannot have a default value.")
1103 if self.group:
1104 fail("A 'defining_class' parameter cannot be in an optional group.")
1105 if self.function.cls is None:
1106 fail("A 'defining_class' parameter cannot be defined at module level.")
1107 kind = inspect.Parameter.POSITIONAL_ONLY
1108 else:
1109 fail("A 'defining_class' parameter, if specified, must either "
1110 "be the first thing in the parameter block, or come just "
1111 "after 'self'.")
1112
1113
1114 p = Parameter(parameter_name, kind, function=self.function,
1115 converter=converter, default=value, group=self.group,
1116 deprecated_positional=self.deprecated_positional)
1117
1118 names = [k.name for k in self.function.parameters.values()]
1119 if parameter_name in names[1:]:
1120 fail(f"You can't have two parameters named {parameter_name!r}!")
1121 elif names and parameter_name == names[0] and c_name is None:
1122 fail(f"Parameter {parameter_name!r} requires a custom C name")
1123
1124 key = f"{parameter_name}_as_{c_name}" if c_name else parameter_name
1125 self.function.parameters[key] = p
1126
1127 if is_vararg:
1128 self.keyword_only = True
1129
1130 @staticmethod
1131 def parse_converter(
1132 annotation: ast.expr | None
1133 ) -> tuple[str, bool, ConverterArgs]:
1134 match annotation:
1135 case ast.Constant(value=str() as value):
1136 return value, True, {}
1137 case ast.Name(name):
1138 return name, False, {}
1139 case ast.Call(func=ast.Name(name)):
1140 kwargs: ConverterArgs = {}
1141 for node in annotation.keywords:
1142 if not isinstance(node.arg, str):
1143 fail("Cannot use a kwarg splat in a function-call annotation")
1144 kwargs[node.arg] = eval_ast_expr(node.value)
1145 return name, False, kwargs
1146 case _:
1147 fail(
1148 "Annotations must be either a name, a function call, or a string."
1149 )
1150
1151 def parse_version(self, thenceforth: str) -> VersionTuple:
1152 """Parse Python version in `[from ...]` marker."""
1153 assert isinstance(self.function, Function)
1154
1155 try:
1156 major, minor = thenceforth.split(".")
1157 return int(major), int(minor)
1158 except ValueError:
1159 fail(
1160 f"Function {self.function.name!r}: expected format '[from major.minor]' "
1161 f"where 'major' and 'minor' are integers; got {thenceforth!r}"
1162 )
1163
1164 def parse_star(self, function: Function, version: VersionTuple | None) -> None:
1165 """Parse keyword-only parameter marker '*'.
1166
1167 The 'version' parameter signifies the future version from which
1168 the marker will take effect (None means it is already in effect).
1169 """
1170 if version is None:
1171 self.check_previous_star()
1172 self.check_remaining_star()
1173 self.keyword_only = True
1174 else:
1175 if self.keyword_only:
1176 fail(f"Function {function.name!r}: '* [from ...]' must precede '*'")
1177 if self.deprecated_positional:
1178 if self.deprecated_positional == version:
1179 fail(f"Function {function.name!r} uses '* [from "
1180 f"{version[0]}.{version[1]}]' more than once.")
1181 if self.deprecated_positional < version:
1182 fail(f"Function {function.name!r}: '* [from "
1183 f"{version[0]}.{version[1]}]' must precede '* [from "
1184 f"{self.deprecated_positional[0]}.{self.deprecated_positional[1]}]'")
1185 self.deprecated_positional = version
1186
1187 def parse_opening_square_bracket(self, function: Function) -> None:
1188 """Parse opening parameter group symbol '['."""
1189 match self.parameter_state:
1190 case ParamState.START | ParamState.LEFT_SQUARE_BEFORE:
1191 self.parameter_state = ParamState.LEFT_SQUARE_BEFORE
1192 case ParamState.REQUIRED | ParamState.GROUP_AFTER:
1193 self.parameter_state = ParamState.GROUP_AFTER
1194 case st:
1195 fail(f"Function {function.name!r} "
1196 f"has an unsupported group configuration. "
1197 f"(Unexpected state {st}.b)")
1198 self.group += 1
1199 function.docstring_only = True
1200
1201 def parse_closing_square_bracket(self, function: Function) -> None:
1202 """Parse closing parameter group symbol ']'."""
1203 if not self.group:
1204 fail(f"Function {function.name!r} has a ']' without a matching '['.")
1205 if not any(p.group == self.group for p in function.parameters.values()):
1206 fail(f"Function {function.name!r} has an empty group. "
1207 "All groups must contain at least one parameter.")
1208 self.group -= 1
1209 match self.parameter_state:
1210 case ParamState.LEFT_SQUARE_BEFORE | ParamState.GROUP_BEFORE:
1211 self.parameter_state = ParamState.GROUP_BEFORE
1212 case ParamState.GROUP_AFTER | ParamState.RIGHT_SQUARE_AFTER:
1213 self.parameter_state = ParamState.RIGHT_SQUARE_AFTER
1214 case st:
1215 fail(f"Function {function.name!r} "
1216 f"has an unsupported group configuration. "
1217 f"(Unexpected state {st}.c)")
1218
1219 def parse_slash(self, function: Function, version: VersionTuple | None) -> None:
1220 """Parse positional-only parameter marker '/'.
1221
1222 The 'version' parameter signifies the future version from which
1223 the marker will take effect (None means it is already in effect).
1224 """
1225 if version is None:
1226 if self.deprecated_keyword:
1227 fail(f"Function {function.name!r}: '/' must precede '/ [from ...]'")
1228 if self.deprecated_positional:
1229 fail(f"Function {function.name!r}: '/' must precede '* [from ...]'")
1230 if self.keyword_only:
1231 fail(f"Function {function.name!r}: '/' must precede '*'")
1232 if self.positional_only:
1233 fail(f"Function {function.name!r} uses '/' more than once.")
1234 else:
1235 if self.deprecated_keyword:
1236 if self.deprecated_keyword == version:
1237 fail(f"Function {function.name!r} uses '/ [from "
1238 f"{version[0]}.{version[1]}]' more than once.")
1239 if self.deprecated_keyword > version:
1240 fail(f"Function {function.name!r}: '/ [from "
1241 f"{version[0]}.{version[1]}]' must precede '/ [from "
1242 f"{self.deprecated_keyword[0]}.{self.deprecated_keyword[1]}]'")
1243 if self.deprecated_positional:
1244 fail(f"Function {function.name!r}: '/ [from ...]' must precede '* [from ...]'")
1245 if self.keyword_only:
1246 fail(f"Function {function.name!r}: '/ [from ...]' must precede '*'")
1247 self.positional_only = True
1248 self.deprecated_keyword = version
1249 if version is not None:
1250 found = False
1251 for p in reversed(function.parameters.values()):
1252 found = p.kind is inspect.Parameter.POSITIONAL_OR_KEYWORD
1253 break
1254 if not found:
1255 fail(f"Function {function.name!r} specifies '/ [from ...]' "
1256 f"without preceding parameters.")
1257 # REQUIRED and OPTIONAL are allowed here, that allows positional-only
1258 # without option groups to work (and have default values!)
1259 allowed = {
1260 ParamState.REQUIRED,
1261 ParamState.OPTIONAL,
1262 ParamState.RIGHT_SQUARE_AFTER,
1263 ParamState.GROUP_BEFORE,
1264 }
1265 if (self.parameter_state not in allowed) or self.group:
1266 fail(f"Function {function.name!r} has an unsupported group configuration. "
1267 f"(Unexpected state {self.parameter_state}.d)")
1268 # fixup preceding parameters
1269 for p in function.parameters.values():
1270 if p.kind is inspect.Parameter.POSITIONAL_OR_KEYWORD:
1271 if version is None:
1272 p.kind = inspect.Parameter.POSITIONAL_ONLY
1273 elif p.deprecated_keyword is None:
1274 p.deprecated_keyword = version
1275
1276 def state_parameter_docstring_start(self, line: str) -> None:
1277 assert self.indent.margin is not None, "self.margin.infer() has not yet been called to set the margin"
1278 self.parameter_docstring_indent = len(self.indent.margin)
1279 assert self.indent.depth == 3
1280 return self.next(self.state_parameter_docstring, line)
1281
1282 def docstring_append(self, obj: Function | Parameter, line: str) -> None:
1283 """Add a rstripped line to the current docstring."""
1284 # gh-80282: We filter out non-ASCII characters from the docstring,
1285 # since historically, some compilers may balk on non-ASCII input.
1286 # If you're using Argument Clinic in an external project,
1287 # you may not need to support the same array of platforms as CPython,
1288 # so you may be able to remove this restriction.
1289 matches = re.finditer(r'[^\x00-\x7F]', line)
1290 if offending := ", ".join([repr(m[0]) for m in matches]):
1291 warn("Non-ascii characters are not allowed in docstrings:",
1292 offending)
1293
1294 docstring = obj.docstring
1295 if docstring:
1296 docstring += "\n"
1297 if stripped := line.rstrip():
1298 docstring += self.indent.dedent(stripped)
1299 obj.docstring = docstring
1300
1301 # every line of the docstring must start with at least F spaces,
1302 # where F > P.
1303 # these F spaces will be stripped.
1304 def state_parameter_docstring(self, line: str) -> None:
1305 if not self.valid_line(line):
1306 return
1307
1308 indent = self.indent.measure(line)
1309 if indent < self.parameter_docstring_indent:
1310 self.indent.infer(line)
1311 assert self.indent.depth < 3
1312 if self.indent.depth == 2:
1313 # back to a parameter
1314 return self.next(self.state_parameter, line)
1315 assert self.indent.depth == 1
1316 return self.next(self.state_function_docstring, line)
1317
1318 assert self.function and self.function.parameters
1319 last_param = next(reversed(self.function.parameters.values()))
1320 self.docstring_append(last_param, line)
1321
1322 # the final stanza of the DSL is the docstring.
1323 def state_function_docstring(self, line: str) -> None:
1324 assert self.function is not None
1325
1326 if self.group:
1327 fail(f"Function {self.function.name!r} has a ']' without a matching '['.")
1328
1329 if not self.valid_line(line):
1330 return
1331
1332 self.docstring_append(self.function, line)
1333
1334 @staticmethod
1335 def format_docstring_signature(
1336 f: Function, parameters: list[Parameter]
1337 ) -> str:
1338 lines = []
1339 lines.append(f.displayname)
1340 if f.forced_text_signature:
1341 lines.append(f.forced_text_signature)
1342 elif f.kind in {GETTER, SETTER}:
1343 # @getter and @setter do not need signatures like a method or a function.
1344 return ''
1345 else:
1346 lines.append('(')
1347
1348 # populate "right_bracket_count" field for every parameter
1349 assert parameters, "We should always have a self parameter. " + repr(f)
1350 assert isinstance(parameters[0].converter, self_converter)
1351 # self is always positional-only.
1352 assert parameters[0].is_positional_only()
1353 assert parameters[0].right_bracket_count == 0
1354 positional_only = True
1355 for p in parameters[1:]:
1356 if not p.is_positional_only():
1357 positional_only = False
1358 else:
1359 assert positional_only
1360 if positional_only:
1361 p.right_bracket_count = abs(p.group)
1362 else:
1363 # don't put any right brackets around non-positional-only parameters, ever.
1364 p.right_bracket_count = 0
1365
1366 right_bracket_count = 0
1367
1368 def fix_right_bracket_count(desired: int) -> str:
1369 nonlocal right_bracket_count
1370 s = ''
1371 while right_bracket_count < desired:
1372 s += '['
1373 right_bracket_count += 1
1374 while right_bracket_count > desired:
1375 s += ']'
1376 right_bracket_count -= 1
1377 return s
1378
1379 need_slash = False
1380 added_slash = False
1381 need_a_trailing_slash = False
1382
1383 # we only need a trailing slash:
1384 # * if this is not a "docstring_only" signature
1385 # * and if the last *shown* parameter is
1386 # positional only
1387 if not f.docstring_only:
1388 for p in reversed(parameters):
1389 if not p.converter.show_in_signature:
1390 continue
1391 if p.is_positional_only():
1392 need_a_trailing_slash = True
1393 break
1394
1395
1396 added_star = False
1397
1398 first_parameter = True
1399 last_p = parameters[-1]
1400 line_length = len(''.join(lines))
1401 indent = " " * line_length
1402 def add_parameter(text: str) -> None:
1403 nonlocal line_length
1404 nonlocal first_parameter
1405 if first_parameter:
1406 s = text
1407 first_parameter = False
1408 else:
1409 s = ' ' + text
1410 if line_length + len(s) >= 72:
1411 lines.extend(["\n", indent])
1412 line_length = len(indent)
1413 s = text
1414 line_length += len(s)
1415 lines.append(s)
1416
1417 for p in parameters:
1418 if not p.converter.show_in_signature:
1419 continue
1420 assert p.name
1421
1422 is_self = isinstance(p.converter, self_converter)
1423 if is_self and f.docstring_only:
1424 # this isn't a real machine-parsable signature,
1425 # so let's not print the "self" parameter
1426 continue
1427
1428 if p.is_positional_only():
1429 need_slash = not f.docstring_only
1430 elif need_slash and not (added_slash or p.is_positional_only()):
1431 added_slash = True
1432 add_parameter('/,')
1433
1434 if p.is_keyword_only() and not added_star:
1435 added_star = True
1436 add_parameter('*,')
1437
1438 p_lines = [fix_right_bracket_count(p.right_bracket_count)]
1439
1440 if isinstance(p.converter, self_converter):
1441 # annotate first parameter as being a "self".
1442 #
1443 # if inspect.Signature gets this function,
1444 # and it's already bound, the self parameter
1445 # will be stripped off.
1446 #
1447 # if it's not bound, it should be marked
1448 # as positional-only.
1449 #
1450 # note: we don't print "self" for __init__,
1451 # because this isn't actually the signature
1452 # for __init__. (it can't be, __init__ doesn't
1453 # have a docstring.) if this is an __init__
1454 # (or __new__), then this signature is for
1455 # calling the class to construct a new instance.
1456 p_lines.append('$')
1457
1458 if p.is_vararg():
1459 p_lines.append("*")
1460 added_star = True
1461
1462 name = p.converter.signature_name or p.name
1463 p_lines.append(name)
1464
1465 if not p.is_vararg() and p.converter.is_optional():
1466 p_lines.append('=')
1467 value = p.converter.py_default
1468 if not value:
1469 value = repr(p.converter.default)
1470 p_lines.append(value)
1471
1472 if (p != last_p) or need_a_trailing_slash:
1473 p_lines.append(',')
1474
1475 p_output = "".join(p_lines)
1476 add_parameter(p_output)
1477
1478 lines.append(fix_right_bracket_count(0))
1479 if need_a_trailing_slash:
1480 add_parameter('/')
1481 lines.append(')')
1482
1483 # PEP 8 says:
1484 #
1485 # The Python standard library will not use function annotations
1486 # as that would result in a premature commitment to a particular
1487 # annotation style. Instead, the annotations are left for users
1488 # to discover and experiment with useful annotation styles.
1489 #
1490 # therefore this is commented out:
1491 #
1492 # if f.return_converter.py_default:
1493 # lines.append(' -> ')
1494 # lines.append(f.return_converter.py_default)
1495
1496 if not f.docstring_only:
1497 lines.append("\n" + libclinic.SIG_END_MARKER + "\n")
1498
1499 signature_line = "".join(lines)
1500
1501 # now fix up the places where the brackets look wrong
1502 return signature_line.replace(', ]', ',] ')
1503
1504 @staticmethod
1505 def format_docstring_parameters(params: list[Parameter]) -> str:
1506 """Create substitution text for {parameters}"""
1507 return "".join(p.render_docstring() + "\n" for p in params if p.docstring)
1508
1509 def format_docstring(self) -> str:
1510 assert self.function is not None
1511 f = self.function
1512 # For the following special cases, it does not make sense to render a docstring.
1513 if f.kind in {METHOD_INIT, METHOD_NEW, GETTER, SETTER} and not f.docstring:
1514 return f.docstring
1515
1516 # Enforce the summary line!
1517 # The first line of a docstring should be a summary of the function.
1518 # It should fit on one line (80 columns? 79 maybe?) and be a paragraph
1519 # by itself.
1520 #
1521 # Argument Clinic enforces the following rule:
1522 # * either the docstring is empty,
1523 # * or it must have a summary line.
1524 #
1525 # Guido said Clinic should enforce this:
1526 # http://mail.python.org/pipermail/python-dev/2013-June/127110.html
1527
1528 lines = f.docstring.split('\n')
1529 if len(lines) >= 2:
1530 if lines[1]:
1531 fail(f"Docstring for {f.full_name!r} does not have a summary line!\n"
1532 "Every non-blank function docstring must start with "
1533 "a single line summary followed by an empty line.")
1534 elif len(lines) == 1:
1535 # the docstring is only one line right now--the summary line.
1536 # add an empty line after the summary line so we have space
1537 # between it and the {parameters} we're about to add.
1538 lines.append('')
1539
1540 parameters_marker_count = len(f.docstring.split('{parameters}')) - 1
1541 if parameters_marker_count > 1:
1542 fail('You may not specify {parameters} more than once in a docstring!')
1543
1544 # insert signature at front and params after the summary line
1545 if not parameters_marker_count:
1546 lines.insert(2, '{parameters}')
1547 lines.insert(0, '{signature}')
1548
1549 # finalize docstring
1550 params = f.render_parameters
1551 parameters = self.format_docstring_parameters(params)
1552 signature = self.format_docstring_signature(f, params)
1553 docstring = "\n".join(lines)
1554 return libclinic.linear_format(docstring,
1555 signature=signature,
1556 parameters=parameters).rstrip()
1557
1558 def check_remaining_star(self, lineno: int | None = None) -> None:
1559 assert isinstance(self.function, Function)
1560
1561 if self.keyword_only:
1562 symbol = '*'
1563 elif self.deprecated_positional:
1564 symbol = '* [from ...]'
1565 else:
1566 return
1567
1568 for p in reversed(self.function.parameters.values()):
1569 if self.keyword_only:
1570 if (p.kind == inspect.Parameter.KEYWORD_ONLY or
1571 p.kind == inspect.Parameter.VAR_POSITIONAL):
1572 return
1573 elif self.deprecated_positional:
1574 if p.deprecated_positional == self.deprecated_positional:
1575 return
1576 break
1577
1578 fail(f"Function {self.function.name!r} specifies {symbol!r} "
1579 f"without following parameters.", line_number=lineno)
1580
1581 def check_previous_star(self) -> None:
1582 assert isinstance(self.function, Function)
1583
1584 if self.keyword_only:
1585 fail(f"Function {self.function.name!r} uses '*' more than once.")
1586
1587
1588 def do_post_block_processing_cleanup(self, lineno: int) -> None:
1589 """
1590 Called when processing the block is done.
1591 """
1592 if not self.function:
1593 return
1594
1595 self.check_remaining_star(lineno)
1596 try:
1597 self.function.docstring = self.format_docstring()
1598 except ClinicError as exc:
1599 exc.lineno = lineno
1600 exc.filename = self.clinic.filename
1601 raise