Debian Codegraph @

Tools/clinic/libclinic/converters.py

raw
1 import builtins as bltns
2 import functools
3 import sys
4 from types import NoneType
5 from typing import Any
6
7 from libclinic import fail, NullType, unspecified, NULL, c_bytes_repr, c_unichar_repr
8 from libclinic.function import (
9 Function, Parameter,
10 CALLABLE, STATIC_METHOD, CLASS_METHOD, METHOD_INIT, METHOD_NEW,
11 GETTER, SETTER)
12 from libclinic.codegen import CRenderData, TemplateDict
13 from libclinic.converter import (
14 CConverter, legacy_converters, add_legacy_c_converter)
15
16
17 TypeSet = set[bltns.type[object]]
18
19
20 class BaseUnsignedIntConverter(CConverter):
21 bitwise = False
22 default_type = int
23 c_ignored_default = '0'
24
25 def use_converter(self) -> None:
26 if self.converter:
27 self.add_include('pycore_long.h',
28 f'{self.converter}()')
29
30 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
31 if not limited_capi:
32 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
33 return self.format_code("""
34 {{{{
35 Py_ssize_t _bytes = PyLong_AsNativeBytes({argname}, &{paramname}, sizeof({type}),
36 Py_ASNATIVEBYTES_NATIVE_ENDIAN |
37 Py_ASNATIVEBYTES_ALLOW_INDEX |
38 Py_ASNATIVEBYTES_REJECT_NEGATIVE |
39 Py_ASNATIVEBYTES_UNSIGNED_BUFFER);
40 if (_bytes < 0) {{{{
41 goto exit;
42 }}}}
43 if ((size_t)_bytes > sizeof({type})) {{{{
44 PyErr_SetString(PyExc_OverflowError,
45 "Python int too large for C {type}");
46 goto exit;
47 }}}}
48 }}}}
49 """,
50 argname=argname,
51 type=self.type)
52
53
54 class uint8_converter(BaseUnsignedIntConverter):
55 type = "uint8_t"
56 converter = '_PyLong_UInt8_Converter'
57
58 class uint16_converter(BaseUnsignedIntConverter):
59 type = "uint16_t"
60 converter = '_PyLong_UInt16_Converter'
61
62 class uint32_converter(BaseUnsignedIntConverter):
63 type = "uint32_t"
64 converter = '_PyLong_UInt32_Converter'
65
66 class uint64_converter(BaseUnsignedIntConverter):
67 type = "uint64_t"
68 converter = '_PyLong_UInt64_Converter'
69
70
71 class bool_converter(CConverter):
72 type = 'int'
73 default_type = bool
74 format_unit = 'p'
75 c_ignored_default = '0'
76
77 def converter_init(self, *, accept: TypeSet = {object}) -> None:
78 if accept == {int}:
79 self.format_unit = 'i'
80 self.default_type = int # type: ignore[assignment]
81 elif accept != {object}:
82 fail(f"bool_converter: illegal 'accept' argument {accept!r}")
83
84 def c_default_init(self) -> None:
85 assert isinstance(self.default, int)
86 self.c_default = str(int(self.default))
87
88 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
89 if self.format_unit == 'i':
90 return self.format_code("""
91 {paramname} = PyLong_AsInt({argname});
92 if ({paramname} == -1 && PyErr_Occurred()) {{{{
93 goto exit;
94 }}}}
95 """,
96 argname=argname)
97 elif self.format_unit == 'p':
98 return self.format_code("""
99 {paramname} = PyObject_IsTrue({argname});
100 if ({paramname} < 0) {{{{
101 goto exit;
102 }}}}
103 """,
104 argname=argname)
105 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
106
107
108 class defining_class_converter(CConverter):
109 """
110 A special-case converter:
111 this is the default converter used for the defining class.
112 """
113 type = 'PyTypeObject *'
114 default_type = ()
115 format_unit = ''
116 show_in_signature = False
117 specified_type: str | None = None
118
119 def converter_init(self, *, type: str | None = None) -> None:
120 self.specified_type = type
121
122 def render(self, parameter: Parameter, data: CRenderData) -> None:
123 self._render_self(parameter, data)
124
125 def set_template_dict(self, template_dict: TemplateDict) -> None:
126 template_dict['defining_class_name'] = self.name
127
128
129 class char_converter(CConverter):
130 type = 'char'
131 default_type = bytes
132 format_unit = 'c'
133 c_ignored_default = "'\0'"
134
135 def converter_init(self) -> None:
136 if isinstance(self.default, self.default_type):
137 if len(self.default) != 1:
138 fail(f"char_converter: illegal default value {self.default!r}")
139
140 def c_default_init(self) -> None:
141 default = self.default
142 assert isinstance(default, bytes)
143 if default == b"'":
144 self.c_default = r"'\''"
145 elif default == b'"':
146 self.c_default = r"""'"'"""
147 elif default == b'\0':
148 self.c_default = r"'\0'"
149 else:
150 r = c_bytes_repr(default)[1:-1]
151 self.c_default = "'" + r + "'"
152
153 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
154 if self.format_unit == 'c':
155 return self.format_code("""
156 if (PyBytes_Check({argname})) {{{{
157 if (PyBytes_GET_SIZE({argname}) != 1) {{{{
158 PyErr_Format(PyExc_TypeError,
159 "{{name}}(): {displayname} must be a byte string of length 1, "
160 "not a bytes object of length %zd",
161 PyBytes_GET_SIZE({argname}));
162 goto exit;
163 }}}}
164 {paramname} = PyBytes_AS_STRING({argname})[0];
165 }}}}
166 else if (PyByteArray_Check({argname})) {{{{
167 if (PyByteArray_GET_SIZE({argname}) != 1) {{{{
168 PyErr_Format(PyExc_TypeError,
169 "{{name}}(): {displayname} must be a byte string of length 1, "
170 "not a bytearray object of length %zd",
171 PyByteArray_GET_SIZE({argname}));
172 goto exit;
173 }}}}
174 {paramname} = PyByteArray_AS_STRING({argname})[0];
175 }}}}
176 else {{{{
177 {bad_argument}
178 goto exit;
179 }}}}
180 """,
181 argname=argname,
182 displayname=displayname,
183 bad_argument=self.bad_argument(displayname, 'a byte string of length 1', limited_capi=limited_capi),
184 )
185 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
186
187
188 @add_legacy_c_converter('B', bitwise=True)
189 class unsigned_char_converter(CConverter):
190 type = 'unsigned char'
191 format_unit = 'b'
192 c_ignored_default = "'\0'"
193
194 def converter_init(self, *, bitwise: bool = False) -> None:
195 if bitwise:
196 self.format_unit = 'B'
197
198 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
199 if self.format_unit == 'b':
200 return self.format_code("""
201 {{{{
202 long ival = PyLong_AsLong({argname});
203 if (ival == -1 && PyErr_Occurred()) {{{{
204 goto exit;
205 }}}}
206 else if (ival < 0) {{{{
207 PyErr_SetString(PyExc_OverflowError,
208 "unsigned byte integer is less than minimum");
209 goto exit;
210 }}}}
211 else if (ival > UCHAR_MAX) {{{{
212 PyErr_SetString(PyExc_OverflowError,
213 "unsigned byte integer is greater than maximum");
214 goto exit;
215 }}}}
216 else {{{{
217 {paramname} = (unsigned char) ival;
218 }}}}
219 }}}}
220 """,
221 argname=argname)
222 elif self.format_unit == 'B':
223 return self.format_code("""
224 {{{{
225 unsigned long ival = PyLong_AsUnsignedLongMask({argname});
226 if (ival == (unsigned long)-1 && PyErr_Occurred()) {{{{
227 goto exit;
228 }}}}
229 else {{{{
230 {paramname} = (unsigned char) ival;
231 }}}}
232 }}}}
233 """,
234 argname=argname)
235 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
236
237
238 class byte_converter(unsigned_char_converter):
239 pass
240
241
242 class short_converter(CConverter):
243 type = 'short'
244 default_type = int
245 format_unit = 'h'
246 c_ignored_default = "0"
247
248 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
249 if self.format_unit == 'h':
250 return self.format_code("""
251 {{{{
252 long ival = PyLong_AsLong({argname});
253 if (ival == -1 && PyErr_Occurred()) {{{{
254 goto exit;
255 }}}}
256 else if (ival < SHRT_MIN) {{{{
257 PyErr_SetString(PyExc_OverflowError,
258 "signed short integer is less than minimum");
259 goto exit;
260 }}}}
261 else if (ival > SHRT_MAX) {{{{
262 PyErr_SetString(PyExc_OverflowError,
263 "signed short integer is greater than maximum");
264 goto exit;
265 }}}}
266 else {{{{
267 {paramname} = (short) ival;
268 }}}}
269 }}}}
270 """,
271 argname=argname)
272 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
273
274
275 class unsigned_short_converter(BaseUnsignedIntConverter):
276 type = 'unsigned short'
277
278 def converter_init(self, *, bitwise: bool = False) -> None:
279 if bitwise:
280 self.format_unit = 'H'
281 else:
282 self.converter = '_PyLong_UnsignedShort_Converter'
283
284 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
285 if self.format_unit == 'H':
286 return self.format_code("""
287 {paramname} = (unsigned short)PyLong_AsUnsignedLongMask({argname});
288 if ({paramname} == (unsigned short)-1 && PyErr_Occurred()) {{{{
289 goto exit;
290 }}}}
291 """,
292 argname=argname)
293 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
294
295
296 @add_legacy_c_converter('C', accept={str})
297 class int_converter(CConverter):
298 type = 'int'
299 default_type = int
300 format_unit = 'i'
301 c_ignored_default = "0"
302
303 def converter_init(
304 self, *, accept: TypeSet = {int}, type: str | None = None
305 ) -> None:
306 if accept == {str}:
307 self.format_unit = 'C'
308 self.default_type = str # type: ignore[assignment]
309 if isinstance(self.default, str):
310 if len(self.default) != 1:
311 fail(f"int_converter: illegal default value {self.default!r}")
312 elif accept != {int}:
313 fail(f"int_converter: illegal 'accept' argument {accept!r}")
314 if type is not None:
315 self.type = type
316
317 def c_default_init(self) -> None:
318 if isinstance(self.default, str):
319 self.c_default = c_unichar_repr(self.default)
320
321 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
322 if self.format_unit == 'i':
323 return self.format_code("""
324 {paramname} = PyLong_AsInt({argname});
325 if ({paramname} == -1 && PyErr_Occurred()) {{{{
326 goto exit;
327 }}}}
328 """,
329 argname=argname)
330 elif self.format_unit == 'C':
331 return self.format_code("""
332 if (!PyUnicode_Check({argname})) {{{{
333 {bad_argument}
334 goto exit;
335 }}}}
336 if (PyUnicode_GET_LENGTH({argname}) != 1) {{{{
337 PyErr_Format(PyExc_TypeError,
338 "{{name}}(): {displayname} must be a unicode character, "
339 "not a string of length %zd",
340 PyUnicode_GET_LENGTH({argname}));
341 goto exit;
342 }}}}
343 {paramname} = PyUnicode_READ_CHAR({argname}, 0);
344 """,
345 argname=argname,
346 displayname=displayname,
347 bad_argument=self.bad_argument(displayname, 'a unicode character', limited_capi=limited_capi),
348 )
349 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
350
351
352 class unsigned_int_converter(BaseUnsignedIntConverter):
353 type = 'unsigned int'
354
355 def converter_init(self, *, bitwise: bool = False) -> None:
356 if bitwise:
357 self.format_unit = 'I'
358 else:
359 self.converter = '_PyLong_UnsignedInt_Converter'
360
361 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
362 if self.format_unit == 'I':
363 return self.format_code("""
364 {paramname} = (unsigned int)PyLong_AsUnsignedLongMask({argname});
365 if ({paramname} == (unsigned int)-1 && PyErr_Occurred()) {{{{
366 goto exit;
367 }}}}
368 """,
369 argname=argname)
370 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
371
372
373 class long_converter(CConverter):
374 type = 'long'
375 default_type = int
376 format_unit = 'l'
377 c_ignored_default = "0"
378
379 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
380 if self.format_unit == 'l':
381 return self.format_code("""
382 {paramname} = PyLong_AsLong({argname});
383 if ({paramname} == -1 && PyErr_Occurred()) {{{{
384 goto exit;
385 }}}}
386 """,
387 argname=argname)
388 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
389
390
391 class unsigned_long_converter(BaseUnsignedIntConverter):
392 type = 'unsigned long'
393
394 def converter_init(self, *, bitwise: bool = False) -> None:
395 if bitwise:
396 self.format_unit = 'k'
397 else:
398 self.converter = '_PyLong_UnsignedLong_Converter'
399
400 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
401 if self.format_unit == 'k':
402 return self.format_code("""
403 if (!PyIndex_Check({argname})) {{{{
404 {bad_argument}
405 goto exit;
406 }}}}
407 {paramname} = PyLong_AsUnsignedLongMask({argname});
408 """,
409 argname=argname,
410 bad_argument=self.bad_argument(displayname, 'int', limited_capi=limited_capi),
411 )
412 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
413
414
415 class long_long_converter(CConverter):
416 type = 'long long'
417 default_type = int
418 format_unit = 'L'
419 c_ignored_default = "0"
420
421 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
422 if self.format_unit == 'L':
423 return self.format_code("""
424 {paramname} = PyLong_AsLongLong({argname});
425 if ({paramname} == -1 && PyErr_Occurred()) {{{{
426 goto exit;
427 }}}}
428 """,
429 argname=argname)
430 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
431
432
433 class unsigned_long_long_converter(BaseUnsignedIntConverter):
434 type = 'unsigned long long'
435
436 def converter_init(self, *, bitwise: bool = False) -> None:
437 if bitwise:
438 self.format_unit = 'K'
439 else:
440 self.converter = '_PyLong_UnsignedLongLong_Converter'
441
442 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
443 if self.format_unit == 'K':
444 return self.format_code("""
445 if (!PyIndex_Check({argname})) {{{{
446 {bad_argument}
447 goto exit;
448 }}}}
449 {paramname} = PyLong_AsUnsignedLongLongMask({argname});
450 """,
451 argname=argname,
452 bad_argument=self.bad_argument(displayname, 'int', limited_capi=limited_capi),
453 )
454 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
455
456
457 class Py_ssize_t_converter(CConverter):
458 type = 'Py_ssize_t'
459 default_type = (int, NoneType)
460 c_ignored_default = "0"
461
462 def converter_init(self, *, accept: TypeSet = {int}) -> None:
463 if accept == {int}:
464 self.format_unit = 'n'
465 self.default_type = int # type: ignore[assignment]
466 elif accept == {int, NoneType}:
467 self.converter = '_Py_convert_optional_to_ssize_t'
468 else:
469 fail(f"Py_ssize_t_converter: illegal 'accept' argument {accept!r}")
470
471 def use_converter(self) -> None:
472 if self.converter == '_Py_convert_optional_to_ssize_t':
473 self.add_include('pycore_abstract.h',
474 '_Py_convert_optional_to_ssize_t()')
475
476 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
477 if self.format_unit == 'n':
478 if limited_capi:
479 PyNumber_Index = 'PyNumber_Index'
480 else:
481 PyNumber_Index = '_PyNumber_Index'
482 self.add_include('pycore_abstract.h', '_PyNumber_Index()')
483 return self.format_code("""
484 {{{{
485 Py_ssize_t ival = -1;
486 PyObject *iobj = {PyNumber_Index}({argname});
487 if (iobj != NULL) {{{{
488 ival = PyLong_AsSsize_t(iobj);
489 Py_DECREF(iobj);
490 }}}}
491 if (ival == -1 && PyErr_Occurred()) {{{{
492 goto exit;
493 }}}}
494 {paramname} = ival;
495 }}}}
496 """,
497 argname=argname,
498 PyNumber_Index=PyNumber_Index)
499 if not limited_capi:
500 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
501 return self.format_code("""
502 if ({argname} != Py_None) {{{{
503 if (PyIndex_Check({argname})) {{{{
504 {paramname} = PyNumber_AsSsize_t({argname}, PyExc_OverflowError);
505 if ({paramname} == -1 && PyErr_Occurred()) {{{{
506 goto exit;
507 }}}}
508 }}}}
509 else {{{{
510 {bad_argument}
511 goto exit;
512 }}}}
513 }}}}
514 """,
515 argname=argname,
516 bad_argument=self.bad_argument(displayname, 'integer or None', limited_capi=limited_capi),
517 )
518
519
520 class slice_index_converter(CConverter):
521 type = 'Py_ssize_t'
522 default_type = (int, NoneType)
523 c_ignored_default = "0"
524
525 def converter_init(self, *, accept: TypeSet = {int, NoneType}) -> None:
526 if accept == {int}:
527 self.converter = '_PyEval_SliceIndexNotNone'
528 self.default_type = int # type: ignore[assignment]
529 self.nullable = False
530 elif accept == {int, NoneType}:
531 self.converter = '_PyEval_SliceIndex'
532 self.nullable = True
533 else:
534 fail(f"slice_index_converter: illegal 'accept' argument {accept!r}")
535
536 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
537 if not limited_capi:
538 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
539 if self.nullable:
540 return self.format_code("""
541 if (!Py_IsNone({argname})) {{{{
542 if (PyIndex_Check({argname})) {{{{
543 {paramname} = PyNumber_AsSsize_t({argname}, NULL);
544 if ({paramname} == -1 && PyErr_Occurred()) {{{{
545 return 0;
546 }}}}
547 }}}}
548 else {{{{
549 PyErr_SetString(PyExc_TypeError,
550 "slice indices must be integers or "
551 "None or have an __index__ method");
552 goto exit;
553 }}}}
554 }}}}
555 """,
556 argname=argname)
557 else:
558 return self.format_code("""
559 if (PyIndex_Check({argname})) {{{{
560 {paramname} = PyNumber_AsSsize_t({argname}, NULL);
561 if ({paramname} == -1 && PyErr_Occurred()) {{{{
562 goto exit;
563 }}}}
564 }}}}
565 else {{{{
566 PyErr_SetString(PyExc_TypeError,
567 "slice indices must be integers or "
568 "have an __index__ method");
569 goto exit;
570 }}}}
571 """,
572 argname=argname)
573
574
575 class size_t_converter(BaseUnsignedIntConverter):
576 type = 'size_t'
577 converter = '_PyLong_Size_t_Converter'
578
579 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
580 if self.format_unit == 'n':
581 return self.format_code("""
582 {paramname} = PyNumber_AsSsize_t({argname}, PyExc_OverflowError);
583 if ({paramname} == -1 && PyErr_Occurred()) {{{{
584 goto exit;
585 }}}}
586 """,
587 argname=argname)
588 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
589
590
591 class fildes_converter(CConverter):
592 type = 'int'
593 converter = '_PyLong_FileDescriptor_Converter'
594
595 def use_converter(self) -> None:
596 self.add_include('pycore_fileutils.h',
597 '_PyLong_FileDescriptor_Converter()')
598
599 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
600 return self.format_code("""
601 {paramname} = PyObject_AsFileDescriptor({argname});
602 if ({paramname} < 0) {{{{
603 goto exit;
604 }}}}
605 """,
606 argname=argname)
607
608
609 class float_converter(CConverter):
610 type = 'float'
611 default_type = float
612 format_unit = 'f'
613 c_ignored_default = "0.0"
614
615 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
616 if self.format_unit == 'f':
617 if not limited_capi:
618 return self.format_code("""
619 if (PyFloat_CheckExact({argname})) {{{{
620 {paramname} = (float) (PyFloat_AS_DOUBLE({argname}));
621 }}}}
622 else
623 {{{{
624 {paramname} = (float) PyFloat_AsDouble({argname});
625 if ({paramname} == -1.0 && PyErr_Occurred()) {{{{
626 goto exit;
627 }}}}
628 }}}}
629 """,
630 argname=argname)
631 else:
632 return self.format_code("""
633 {paramname} = (float) PyFloat_AsDouble({argname});
634 if ({paramname} == -1.0 && PyErr_Occurred()) {{{{
635 goto exit;
636 }}}}
637 """,
638 argname=argname)
639 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
640
641
642 class double_converter(CConverter):
643 type = 'double'
644 default_type = float
645 format_unit = 'd'
646 c_ignored_default = "0.0"
647
648 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
649 if self.format_unit == 'd':
650 if not limited_capi:
651 return self.format_code("""
652 if (PyFloat_CheckExact({argname})) {{{{
653 {paramname} = PyFloat_AS_DOUBLE({argname});
654 }}}}
655 else
656 {{{{
657 {paramname} = PyFloat_AsDouble({argname});
658 if ({paramname} == -1.0 && PyErr_Occurred()) {{{{
659 goto exit;
660 }}}}
661 }}}}
662 """,
663 argname=argname)
664 else:
665 return self.format_code("""
666 {paramname} = PyFloat_AsDouble({argname});
667 if ({paramname} == -1.0 && PyErr_Occurred()) {{{{
668 goto exit;
669 }}}}
670 """,
671 argname=argname)
672 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
673
674
675 class Py_complex_converter(CConverter):
676 type = 'Py_complex'
677 default_type = complex
678 format_unit = 'D'
679 c_ignored_default = "{0.0, 0.0}"
680
681 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
682 if self.format_unit == 'D':
683 return self.format_code("""
684 {paramname} = PyComplex_AsCComplex({argname});
685 if (PyErr_Occurred()) {{{{
686 goto exit;
687 }}}}
688 """,
689 argname=argname)
690 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
691
692
693 class object_converter(CConverter):
694 type = 'PyObject *'
695 format_unit = 'O'
696 c_ignored_default = 'NULL'
697
698 def converter_init(
699 self, *,
700 converter: str | None = None,
701 type: str | None = None,
702 subclass_of: str | None = None
703 ) -> None:
704 if converter:
705 if subclass_of:
706 fail("object: Cannot pass in both 'converter' and 'subclass_of'")
707 self.format_unit = 'O&'
708 self.converter = converter
709 elif subclass_of:
710 self.format_unit = 'O!'
711 self.subclass_of = subclass_of
712
713 if type is not None:
714 self.type = type
715
716 def c_default_init(self) -> None:
717 default = self.default
718 if default is None or isinstance(default, bool):
719 self.c_default = "Py_" + repr(default)
720
721 #
722 # We define three conventions for buffer types in the 'accept' argument:
723 #
724 # buffer : any object supporting the buffer interface
725 # rwbuffer: any object supporting the buffer interface, but must be writeable
726 # robuffer: any object supporting the buffer interface, but must not be writeable
727 #
728
729 class buffer:
730 pass
731 class rwbuffer:
732 pass
733 class robuffer:
734 pass
735
736
737 StrConverterKeyType = tuple[frozenset[type[object]], bool, bool]
738
739 def str_converter_key(
740 types: TypeSet, encoding: bool | str | None, zeroes: bool
741 ) -> StrConverterKeyType:
742 return (frozenset(types), bool(encoding), bool(zeroes))
743
744 str_converter_argument_map: dict[StrConverterKeyType, str] = {}
745
746
747 class str_converter(CConverter):
748 type = 'const char *'
749 default_type = (str, bytes, NullType, NoneType)
750 format_unit = 's'
751 c_ignored_default = 'NULL'
752
753 def converter_init(
754 self,
755 *,
756 accept: TypeSet = {str},
757 encoding: str | None = None,
758 zeroes: bool = False
759 ) -> None:
760
761 key = str_converter_key(accept, encoding, zeroes)
762 format_unit = str_converter_argument_map.get(key)
763 if not format_unit:
764 fail("str_converter: illegal combination of arguments", key)
765
766 self.format_unit = format_unit
767 self.length = bool(zeroes)
768 if encoding:
769 if self.default not in (NULL, None, unspecified):
770 fail("str_converter: Argument Clinic doesn't support default values for encoded strings")
771 self.encoding = encoding
772 self.type = 'char *'
773 # sorry, clinic can't support preallocated buffers
774 # for es# and et#
775 self.c_default = "NULL"
776
777 def c_default_init(self) -> None:
778 if self.default is None:
779 self.c_default = "NULL"
780
781 def post_parsing(self) -> str:
782 if self.encoding:
783 name = self.name
784 return f"PyMem_FREE({name});\n"
785 else:
786 return ""
787
788 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
789 if self.format_unit == 's':
790 return self.format_code("""
791 if (!PyUnicode_Check({argname})) {{{{
792 {bad_argument}
793 goto exit;
794 }}}}
795 Py_ssize_t {length_name};
796 {paramname} = PyUnicode_AsUTF8AndSize({argname}, &{length_name});
797 if ({paramname} == NULL) {{{{
798 goto exit;
799 }}}}
800 if (strlen({paramname}) != (size_t){length_name}) {{{{
801 PyErr_SetString(PyExc_ValueError, "embedded null character");
802 goto exit;
803 }}}}
804 """,
805 argname=argname,
806 bad_argument=self.bad_argument(displayname, 'str', limited_capi=limited_capi),
807 length_name=self.length_name)
808 if self.format_unit == 'z':
809 return self.format_code("""
810 if ({argname} == Py_None) {{{{
811 {paramname} = NULL;
812 }}}}
813 else if (PyUnicode_Check({argname})) {{{{
814 Py_ssize_t {length_name};
815 {paramname} = PyUnicode_AsUTF8AndSize({argname}, &{length_name});
816 if ({paramname} == NULL) {{{{
817 goto exit;
818 }}}}
819 if (strlen({paramname}) != (size_t){length_name}) {{{{
820 PyErr_SetString(PyExc_ValueError, "embedded null character");
821 goto exit;
822 }}}}
823 }}}}
824 else {{{{
825 {bad_argument}
826 goto exit;
827 }}}}
828 """,
829 argname=argname,
830 bad_argument=self.bad_argument(displayname, 'str or None', limited_capi=limited_capi),
831 length_name=self.length_name)
832 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
833
834 #
835 # This is the fourth or fifth rewrite of registering all the
836 # string converter format units. Previous approaches hid
837 # bugs--generally mismatches between the semantics of the format
838 # unit and the arguments necessary to represent those semantics
839 # properly. Hopefully with this approach we'll get it 100% right.
840 #
841 # The r() function (short for "register") both registers the
842 # mapping from arguments to format unit *and* registers the
843 # legacy C converter for that format unit.
844 #
845 def r(format_unit: str,
846 *,
847 accept: TypeSet,
848 encoding: bool = False,
849 zeroes: bool = False
850 ) -> None:
851 if not encoding and format_unit != 's':
852 # add the legacy c converters here too.
853 #
854 # note: add_legacy_c_converter can't work for
855 # es, es#, et, or et#
856 # because of their extra encoding argument
857 #
858 # also don't add the converter for 's' because
859 # the metaclass for CConverter adds it for us.
860 kwargs: dict[str, Any] = {}
861 if accept != {str}:
862 kwargs['accept'] = accept
863 if zeroes:
864 kwargs['zeroes'] = True
865 added_f = functools.partial(str_converter, **kwargs)
866 legacy_converters[format_unit] = added_f
867
868 d = str_converter_argument_map
869 key = str_converter_key(accept, encoding, zeroes)
870 if key in d:
871 sys.exit("Duplicate keys specified for str_converter_argument_map!")
872 d[key] = format_unit
873
874 r('es', encoding=True, accept={str})
875 r('es#', encoding=True, zeroes=True, accept={str})
876 r('et', encoding=True, accept={bytes, bytearray, str})
877 r('et#', encoding=True, zeroes=True, accept={bytes, bytearray, str})
878 r('s', accept={str})
879 r('s#', zeroes=True, accept={robuffer, str})
880 r('y', accept={robuffer})
881 r('y#', zeroes=True, accept={robuffer})
882 r('z', accept={str, NoneType})
883 r('z#', zeroes=True, accept={robuffer, str, NoneType})
884 del r
885
886
887 class PyBytesObject_converter(CConverter):
888 type = 'PyBytesObject *'
889 format_unit = 'S'
890 # accept = {bytes}
891 c_ignored_default = 'NULL'
892
893 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
894 if self.format_unit == 'S':
895 return self.format_code("""
896 if (!PyBytes_Check({argname})) {{{{
897 {bad_argument}
898 goto exit;
899 }}}}
900 {paramname} = ({type}){argname};
901 """,
902 argname=argname,
903 bad_argument=self.bad_argument(displayname, 'bytes', limited_capi=limited_capi),
904 type=self.type)
905 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
906
907
908 class PyByteArrayObject_converter(CConverter):
909 type = 'PyByteArrayObject *'
910 format_unit = 'Y'
911 # accept = {bytearray}
912 c_ignored_default = 'NULL'
913
914 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
915 if self.format_unit == 'Y':
916 return self.format_code("""
917 if (!PyByteArray_Check({argname})) {{{{
918 {bad_argument}
919 goto exit;
920 }}}}
921 {paramname} = ({type}){argname};
922 """,
923 argname=argname,
924 bad_argument=self.bad_argument(displayname, 'bytearray', limited_capi=limited_capi),
925 type=self.type)
926 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
927
928
929 class unicode_converter(CConverter):
930 type = 'PyObject *'
931 default_type = (str, NullType, NoneType)
932 format_unit = 'U'
933 c_ignored_default = 'NULL'
934
935 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
936 if self.format_unit == 'U':
937 return self.format_code("""
938 if (!PyUnicode_Check({argname})) {{{{
939 {bad_argument}
940 goto exit;
941 }}}}
942 {paramname} = {argname};
943 """,
944 argname=argname,
945 bad_argument=self.bad_argument(displayname, 'str', limited_capi=limited_capi),
946 )
947 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
948
949
950 class _unicode_fs_converter_base(CConverter):
951 type = 'PyObject *'
952 default_type = NullType
953 c_init_default = 'NULL'
954
955 def c_default_init(self) -> None:
956 fail(f"{self.__class__.__name__} does not support default values")
957
958 def cleanup(self) -> str:
959 return f"Py_XDECREF({self.parser_name});"
960
961
962 class unicode_fs_encoded_converter(_unicode_fs_converter_base):
963 converter = 'PyUnicode_FSConverter'
964
965
966 class unicode_fs_decoded_converter(_unicode_fs_converter_base):
967 converter = 'PyUnicode_FSDecoder'
968
969
970 @add_legacy_c_converter('u')
971 @add_legacy_c_converter('u#', zeroes=True)
972 @add_legacy_c_converter('Z', accept={str, NoneType})
973 @add_legacy_c_converter('Z#', accept={str, NoneType}, zeroes=True)
974 class Py_UNICODE_converter(CConverter):
975 type = 'const wchar_t *'
976 default_type = (str, NullType, NoneType)
977 c_ignored_default = 'NULL'
978
979 def converter_init(
980 self, *,
981 accept: TypeSet = {str},
982 zeroes: bool = False
983 ) -> None:
984 format_unit = 'Z' if accept=={str, NoneType} else 'u'
985 if zeroes:
986 format_unit += '#'
987 self.length = True
988 self.format_unit = format_unit
989 else:
990 self.accept = accept
991 if accept == {str}:
992 self.converter = '_PyUnicode_WideCharString_Converter'
993 self.default_type = (str, NullType) # type: ignore[assignment]
994 elif accept == {str, NoneType}:
995 self.converter = '_PyUnicode_WideCharString_Opt_Converter'
996 else:
997 fail(f"Py_UNICODE_converter: illegal 'accept' argument {accept!r}")
998 self.c_default = "NULL"
999
1000 def cleanup(self) -> str:
1001 if self.length:
1002 return ""
1003 else:
1004 return f"""PyMem_Free((void *){self.parser_name});\n"""
1005
1006 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
1007 if not self.length:
1008 if self.accept == {str}:
1009 return self.format_code("""
1010 if (!PyUnicode_Check({argname})) {{{{
1011 {bad_argument}
1012 goto exit;
1013 }}}}
1014 {paramname} = PyUnicode_AsWideCharString({argname}, NULL);
1015 if ({paramname} == NULL) {{{{
1016 goto exit;
1017 }}}}
1018 """,
1019 argname=argname,
1020 bad_argument=self.bad_argument(displayname, 'str', limited_capi=limited_capi),
1021 )
1022 elif self.accept == {str, NoneType}:
1023 return self.format_code("""
1024 if ({argname} == Py_None) {{{{
1025 {paramname} = NULL;
1026 }}}}
1027 else if (PyUnicode_Check({argname})) {{{{
1028 {paramname} = PyUnicode_AsWideCharString({argname}, NULL);
1029 if ({paramname} == NULL) {{{{
1030 goto exit;
1031 }}}}
1032 }}}}
1033 else {{{{
1034 {bad_argument}
1035 goto exit;
1036 }}}}
1037 """,
1038 argname=argname,
1039 bad_argument=self.bad_argument(displayname, 'str or None', limited_capi=limited_capi),
1040 )
1041 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
1042
1043
1044 @add_legacy_c_converter('s*', accept={str, buffer})
1045 @add_legacy_c_converter('z*', accept={str, buffer, NoneType})
1046 @add_legacy_c_converter('w*', accept={rwbuffer})
1047 class Py_buffer_converter(CConverter):
1048 type = 'Py_buffer'
1049 default_type = (str, bytes, NullType, NoneType)
1050 format_unit = 'y*'
1051 impl_by_reference = True
1052 c_init_default = "{NULL, NULL}"
1053
1054 def converter_init(self, *, accept: TypeSet = {buffer}) -> None:
1055 if accept == {str, buffer, NoneType}:
1056 self.format_unit = 'z*'
1057 self.default_type = (str, bytes, NullType, NoneType)
1058 elif accept == {str, buffer}:
1059 self.format_unit = 's*'
1060 self.default_type = (str, bytes, NullType) # type: ignore[assignment]
1061 elif accept == {buffer}:
1062 self.format_unit = 'y*'
1063 self.default_type = (bytes, NullType) # type: ignore[assignment]
1064 elif accept == {rwbuffer}:
1065 self.format_unit = 'w*'
1066 self.default_type = NullType # type: ignore[assignment]
1067 else:
1068 fail("Py_buffer_converter: illegal combination of arguments")
1069
1070 def c_default_init(self) -> None:
1071 default = self.default
1072 if isinstance(default, bytes):
1073 self.c_default = f'{{.buf = {c_bytes_repr(default)}, .obj = NULL, .len = {len(default)}}}'
1074 elif isinstance(default, str):
1075 default = default.encode()
1076 self.c_default = f'{{.buf = {c_bytes_repr(default)}, .obj = NULL, .len = {len(default)}}}'
1077
1078 def cleanup(self) -> str:
1079 name = self.name
1080 return "".join(["if (", name, ".obj) {\n PyBuffer_Release(&", name, ");\n}\n"])
1081
1082 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
1083 # PyBUF_SIMPLE guarantees that the format units of the buffers are C-contiguous.
1084 if self.format_unit == 'y*':
1085 return self.format_code("""
1086 if (PyObject_GetBuffer({argname}, &{paramname}, PyBUF_SIMPLE) != 0) {{{{
1087 goto exit;
1088 }}}}
1089 """,
1090 argname=argname,
1091 bad_argument=self.bad_argument(displayname, 'contiguous buffer', limited_capi=limited_capi),
1092 )
1093 elif self.format_unit == 's*':
1094 return self.format_code("""
1095 if (PyUnicode_Check({argname})) {{{{
1096 Py_ssize_t len;
1097 const char *ptr = PyUnicode_AsUTF8AndSize({argname}, &len);
1098 if (ptr == NULL) {{{{
1099 goto exit;
1100 }}}}
1101 if (PyBuffer_FillInfo(&{paramname}, {argname}, (void *)ptr, len, 1, PyBUF_SIMPLE) < 0) {{{{
1102 goto exit;
1103 }}}}
1104 }}}}
1105 else {{{{ /* any bytes-like object */
1106 if (PyObject_GetBuffer({argname}, &{paramname}, PyBUF_SIMPLE) != 0) {{{{
1107 goto exit;
1108 }}}}
1109 }}}}
1110 """,
1111 argname=argname,
1112 bad_argument=self.bad_argument(displayname, 'contiguous buffer', limited_capi=limited_capi),
1113 )
1114 elif self.format_unit == 'w*':
1115 return self.format_code("""
1116 if (PyObject_GetBuffer({argname}, &{paramname}, PyBUF_WRITABLE) < 0) {{{{
1117 {bad_argument}
1118 goto exit;
1119 }}}}
1120 """,
1121 argname=argname,
1122 bad_argument=self.bad_argument(displayname, 'read-write bytes-like object', limited_capi=limited_capi),
1123 bad_argument2=self.bad_argument(displayname, 'contiguous buffer', limited_capi=limited_capi),
1124 )
1125 return super().parse_arg(argname, displayname, limited_capi=limited_capi)
1126
1127
1128 def correct_name_for_self(
1129 f: Function,
1130 parser: bool = False
1131 ) -> tuple[str, str]:
1132 if f.kind in {CALLABLE, METHOD_INIT, GETTER, SETTER}:
1133 if f.cls:
1134 return "PyObject *", "self"
1135 return "PyObject *", "module"
1136 if f.kind is STATIC_METHOD:
1137 if parser:
1138 return "PyObject *", "null"
1139 else:
1140 return "void *", "null"
1141 if f.kind == CLASS_METHOD:
1142 if parser:
1143 return "PyObject *", "type"
1144 else:
1145 return "PyTypeObject *", "type"
1146 if f.kind == METHOD_NEW:
1147 return "PyTypeObject *", "type"
1148 raise AssertionError(f"Unhandled type of function f: {f.kind!r}")
1149
1150
1151 class self_converter(CConverter):
1152 """
1153 A special-case converter:
1154 this is the default converter used for "self".
1155 """
1156 type: str | None = None
1157 default_type = ()
1158 format_unit = ''
1159 specified_type: str | None = None
1160
1161 def converter_init(self, *, type: str | None = None) -> None:
1162 self.specified_type = type
1163
1164 def pre_render(self) -> None:
1165 f = self.function
1166 default_type, default_name = correct_name_for_self(f)
1167 self.signature_name = default_name
1168 self.type = self.specified_type or self.type or default_type
1169
1170 kind = self.function.kind
1171
1172 if kind is STATIC_METHOD or kind.new_or_init:
1173 self.show_in_signature = False
1174
1175 # tp_new (METHOD_NEW) functions are of type newfunc:
1176 # typedef PyObject *(*newfunc)(PyTypeObject *, PyObject *, PyObject *);
1177 #
1178 # tp_init (METHOD_INIT) functions are of type initproc:
1179 # typedef int (*initproc)(PyObject *, PyObject *, PyObject *);
1180 #
1181 # All other functions generated by Argument Clinic are stored in
1182 # PyMethodDef structures, in the ml_meth slot, which is of type PyCFunction:
1183 # typedef PyObject *(*PyCFunction)(PyObject *, PyObject *);
1184 # However! We habitually cast these functions to PyCFunction,
1185 # since functions that accept keyword arguments don't fit this signature
1186 # but are stored there anyway. So strict type equality isn't important
1187 # for these functions.
1188 #
1189 # So:
1190 #
1191 # * The name of the first parameter to the impl and the parsing function will always
1192 # be self.name.
1193 #
1194 # * The type of the first parameter to the impl will always be of self.type.
1195 #
1196 # * If the function is neither tp_new (METHOD_NEW) nor tp_init (METHOD_INIT):
1197 # * The type of the first parameter to the parsing function is also self.type.
1198 # This means that if you step into the parsing function, your "self" parameter
1199 # is of the correct type, which may make debugging more pleasant.
1200 #
1201 # * Else if the function is tp_new (METHOD_NEW):
1202 # * The type of the first parameter to the parsing function is "PyTypeObject *",
1203 # so the type signature of the function call is an exact match.
1204 # * If self.type != "PyTypeObject *", we cast the first parameter to self.type
1205 # in the impl call.
1206 #
1207 # * Else if the function is tp_init (METHOD_INIT):
1208 # * The type of the first parameter to the parsing function is "PyObject *",
1209 # so the type signature of the function call is an exact match.
1210 # * If self.type != "PyObject *", we cast the first parameter to self.type
1211 # in the impl call.
1212
1213 @property
1214 def parser_type(self) -> str:
1215 assert self.type is not None
1216 tp, _ = correct_name_for_self(self.function, parser=True)
1217 return tp
1218
1219 def render(self, parameter: Parameter, data: CRenderData) -> None:
1220 """
1221 parameter is a clinic.Parameter instance.
1222 data is a CRenderData instance.
1223 """
1224 if self.function.kind is STATIC_METHOD:
1225 return
1226
1227 self._render_self(parameter, data)
1228
1229 if self.type != self.parser_type:
1230 # insert cast to impl_argument[0], aka self.
1231 # we know we're in the first slot in all the CRenderData lists,
1232 # because we render parameters in order, and self is always first.
1233 assert len(data.impl_arguments) == 1
1234 assert data.impl_arguments[0] == self.name
1235 assert self.type is not None
1236 data.impl_arguments[0] = '(' + self.type + ")" + data.impl_arguments[0]
1237
1238 def set_template_dict(self, template_dict: TemplateDict) -> None:
1239 template_dict['self_name'] = self.name
1240 template_dict['self_type'] = self.parser_type
1241 kind = self.function.kind
1242 cls = self.function.cls
1243
1244 if kind.new_or_init and cls and cls.typedef:
1245 if kind is METHOD_NEW:
1246 type_check = (
1247 '({0} == base_tp || {0}->tp_init == base_tp->tp_init)'
1248 ).format(self.name)
1249 else:
1250 type_check = ('(Py_IS_TYPE({0}, base_tp) ||\n '
1251 ' Py_TYPE({0})->tp_new == base_tp->tp_new)'
1252 ).format(self.name)
1253
1254 line = f'{type_check} &&\n '
1255 template_dict['self_type_check'] = line
1256
1257 type_object = cls.type_object
1258 type_ptr = f'PyTypeObject *base_tp = {type_object};'
1259 template_dict['base_type_ptr'] = type_ptr
1260
1261 def use_pyobject_self(self, func: Function) -> bool:
1262 conv_type = self.type
1263 if conv_type is None:
1264 conv_type, _ = correct_name_for_self(func)
1265 return (conv_type in ('PyObject *', None)
1266 and self.specified_type in ('PyObject *', None))
1267
1268
1269 # Converters for var-positional parameter.
1270
1271 class VarPosCConverter(CConverter):
1272 default_type = ()
1273 format_unit = ''
1274
1275 def parse_arg(self, argname: str, displayname: str, *, limited_capi: bool) -> str | None:
1276 raise AssertionError('should never be called')
1277
1278 def parse_vararg(self, *, pos_only: int, min_pos: int, max_pos: int,
1279 fastcall: bool, limited_capi: bool) -> str:
1280 raise NotImplementedError
1281
1282
1283 class varpos_tuple_converter(VarPosCConverter):
1284 type = 'PyObject *'
1285 c_init_default = 'NULL'
1286
1287 def cleanup(self) -> str:
1288 return f"""Py_XDECREF({self.parser_name});\n"""
1289
1290 def parse_vararg(self, *, pos_only: int, min_pos: int, max_pos: int,
1291 fastcall: bool, limited_capi: bool) -> str:
1292 paramname = self.parser_name
1293 if fastcall:
1294 if limited_capi:
1295 if min(pos_only, min_pos) < max_pos:
1296 size = f'Py_MAX(nargs - {max_pos}, 0)'
1297 else:
1298 size = f'nargs - {max_pos}' if max_pos else 'nargs'
1299 return f"""
1300 {paramname} = PyTuple_New({size});
1301 if (!{paramname}) {{{{
1302 goto exit;
1303 }}}}
1304 for (Py_ssize_t i = {max_pos}; i < nargs; ++i) {{{{
1305 PyTuple_SET_ITEM({paramname}, i - {max_pos}, Py_NewRef(args[i]));
1306 }}}}
1307 """
1308 else:
1309 self.add_include('pycore_tuple.h', '_PyTuple_FromArray()')
1310 start = f'args + {max_pos}' if max_pos else 'args'
1311 size = f'nargs - {max_pos}' if max_pos else 'nargs'
1312 if min(pos_only, min_pos) < max_pos:
1313 return f"""
1314 {paramname} = nargs > {max_pos}
1315 ? _PyTuple_FromArray({start}, {size})
1316 : PyTuple_New(0);
1317 if ({paramname} == NULL) {{{{
1318 goto exit;
1319 }}}}
1320 """
1321 else:
1322 return f"""
1323 {paramname} = _PyTuple_FromArray({start}, {size});
1324 if ({paramname} == NULL) {{{{
1325 goto exit;
1326 }}}}
1327 """
1328 else:
1329 if max_pos:
1330 return f"""
1331 {paramname} = PyTuple_GetSlice(args, {max_pos}, PY_SSIZE_T_MAX);
1332 if (!{paramname}) {{{{
1333 goto exit;
1334 }}}}
1335 """
1336 else:
1337 return f"{paramname} = Py_NewRef(args);\n"
1338
1339
1340 class varpos_array_converter(VarPosCConverter):
1341 type = 'PyObject * const *'
1342 length = True
1343
1344 def parse_vararg(self, *, pos_only: int, min_pos: int, max_pos: int,
1345 fastcall: bool, limited_capi: bool) -> str:
1346 paramname = self.parser_name
1347 if not fastcall:
1348 self.add_include('pycore_tuple.h', '_PyTuple_ITEMS()')
1349 start = 'args' if fastcall else '_PyTuple_ITEMS(args)'
1350 size = 'nargs' if fastcall else 'PyTuple_GET_SIZE(args)'
1351 if max_pos:
1352 if min(pos_only, min_pos) < max_pos:
1353 start = f'{size} > {max_pos} ? {start} + {max_pos} : {start}'
1354 size = f'Py_MAX(0, {size} - {max_pos})'
1355 else:
1356 start = f'{start} + {max_pos}'
1357 size = f'{size} - {max_pos}'
1358 return f"""
1359 {paramname} = {start};
1360 {self.length_name} = {size};
1361 """