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