| 1 |
from __future__ import annotations |
| 2 |
from typing import TYPE_CHECKING, Final |
| 3 |
|
| 4 |
import libclinic |
| 5 |
from libclinic import fail, warn |
| 6 |
from libclinic.function import ( |
| 7 |
Function, Parameter, |
| 8 |
GETTER, SETTER, METHOD_NEW) |
| 9 |
from libclinic.converter import CConverter |
| 10 |
from libclinic.converters import ( |
| 11 |
defining_class_converter, object_converter, self_converter) |
| 12 |
if TYPE_CHECKING: |
| 13 |
from libclinic.clanguage import CLanguage |
| 14 |
from libclinic.codegen import CodeGen |
| 15 |
|
| 16 |
|
| 17 |
def declare_parser( |
| 18 |
f: Function, |
| 19 |
*, |
| 20 |
hasformat: bool = False, |
| 21 |
codegen: CodeGen, |
| 22 |
) -> str: |
| 23 |
""" |
| 24 |
Generates the code template for a static local PyArg_Parser variable, |
| 25 |
with an initializer. For core code (incl. builtin modules) the |
| 26 |
kwtuple field is also statically initialized. Otherwise |
| 27 |
it is initialized at runtime. |
| 28 |
""" |
| 29 |
limited_capi = codegen.limited_capi |
| 30 |
if hasformat: |
| 31 |
fname = '' |
| 32 |
format_ = '.format = "{format_units}:{name}",' |
| 33 |
else: |
| 34 |
fname = '.fname = "{name}",' |
| 35 |
format_ = '' |
| 36 |
|
| 37 |
num_keywords = len([ |
| 38 |
p for p in f.parameters.values() |
| 39 |
if not p.is_positional_only() and not p.is_vararg() |
| 40 |
]) |
| 41 |
|
| 42 |
condition = '#if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)' |
| 43 |
if limited_capi: |
| 44 |
declarations = """ |
| 45 |
#define KWTUPLE NULL |
| 46 |
""" |
| 47 |
elif num_keywords == 0: |
| 48 |
declarations = """ |
| 49 |
#if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE) |
| 50 |
# define KWTUPLE (PyObject *)&_Py_SINGLETON(tuple_empty) |
| 51 |
#else |
| 52 |
# define KWTUPLE NULL |
| 53 |
#endif |
| 54 |
""" |
| 55 |
|
| 56 |
codegen.add_include('pycore_runtime.h', '_Py_SINGLETON()', |
| 57 |
condition=condition) |
| 58 |
else: |
| 59 |
# XXX Why do we not statically allocate the tuple |
| 60 |
# for non-builtin modules? |
| 61 |
declarations = """ |
| 62 |
#if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE) |
| 63 |
|
| 64 |
#define NUM_KEYWORDS %d |
| 65 |
static struct {{ |
| 66 |
PyGC_Head _this_is_not_used; |
| 67 |
PyObject_VAR_HEAD |
| 68 |
Py_hash_t ob_hash; |
| 69 |
PyObject *ob_item[NUM_KEYWORDS]; |
| 70 |
}} _kwtuple = {{ |
| 71 |
.ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS) |
| 72 |
.ob_hash = -1, |
| 73 |
.ob_item = {{ {keywords_py} }}, |
| 74 |
}}; |
| 75 |
#undef NUM_KEYWORDS |
| 76 |
#define KWTUPLE (&_kwtuple.ob_base.ob_base) |
| 77 |
|
| 78 |
#else // !Py_BUILD_CORE |
| 79 |
# define KWTUPLE NULL |
| 80 |
#endif // !Py_BUILD_CORE |
| 81 |
""" % num_keywords |
| 82 |
|
| 83 |
codegen.add_include('pycore_gc.h', 'PyGC_Head', |
| 84 |
condition=condition) |
| 85 |
codegen.add_include('pycore_runtime.h', '_Py_ID()', |
| 86 |
condition=condition) |
| 87 |
|
| 88 |
declarations += """ |
| 89 |
static const char * const _keywords[] = {{{keywords_c} NULL}}; |
| 90 |
static _PyArg_Parser _parser = {{ |
| 91 |
.keywords = _keywords, |
| 92 |
%s |
| 93 |
.kwtuple = KWTUPLE, |
| 94 |
}}; |
| 95 |
#undef KWTUPLE |
| 96 |
""" % (format_ or fname) |
| 97 |
return libclinic.normalize_snippet(declarations) |
| 98 |
|
| 99 |
|
| 100 |
NO_VARARG: Final[str] = "PY_SSIZE_T_MAX" |
| 101 |
PARSER_PROTOTYPE_KEYWORD: Final[str] = libclinic.normalize_snippet(""" |
| 102 |
static PyObject * |
| 103 |
{c_basename}({self_type}{self_name}, PyObject *args, PyObject *kwargs) |
| 104 |
""") |
| 105 |
PARSER_PROTOTYPE_KEYWORD___INIT__: Final[str] = libclinic.normalize_snippet(""" |
| 106 |
static int |
| 107 |
{c_basename}({self_type}{self_name}, PyObject *args, PyObject *kwargs) |
| 108 |
""") |
| 109 |
PARSER_PROTOTYPE_VARARGS: Final[str] = libclinic.normalize_snippet(""" |
| 110 |
static PyObject * |
| 111 |
{c_basename}({self_type}{self_name}, PyObject *args) |
| 112 |
""") |
| 113 |
PARSER_PROTOTYPE_FASTCALL: Final[str] = libclinic.normalize_snippet(""" |
| 114 |
static PyObject * |
| 115 |
{c_basename}({self_type}{self_name}, PyObject *const *args, Py_ssize_t nargs) |
| 116 |
""") |
| 117 |
PARSER_PROTOTYPE_FASTCALL_KEYWORDS: Final[str] = libclinic.normalize_snippet(""" |
| 118 |
static PyObject * |
| 119 |
{c_basename}({self_type}{self_name}, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames) |
| 120 |
""") |
| 121 |
PARSER_PROTOTYPE_DEF_CLASS: Final[str] = libclinic.normalize_snippet(""" |
| 122 |
static PyObject * |
| 123 |
{c_basename}({self_type}{self_name}, PyTypeObject *{defining_class_name}, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames) |
| 124 |
""") |
| 125 |
PARSER_PROTOTYPE_NOARGS: Final[str] = libclinic.normalize_snippet(""" |
| 126 |
static PyObject * |
| 127 |
{c_basename}({self_type}{self_name}, PyObject *Py_UNUSED(ignored)) |
| 128 |
""") |
| 129 |
PARSER_PROTOTYPE_GETTER: Final[str] = libclinic.normalize_snippet(""" |
| 130 |
static PyObject * |
| 131 |
{c_basename}({self_type}{self_name}, void *Py_UNUSED(context)) |
| 132 |
""") |
| 133 |
PARSER_PROTOTYPE_SETTER: Final[str] = libclinic.normalize_snippet(""" |
| 134 |
static int |
| 135 |
{c_basename}({self_type}{self_name}, PyObject *value, void *Py_UNUSED(context)) |
| 136 |
""") |
| 137 |
METH_O_PROTOTYPE: Final[str] = libclinic.normalize_snippet(""" |
| 138 |
static PyObject * |
| 139 |
{c_basename}({self_type}{self_name}, {parser_parameters}) |
| 140 |
""") |
| 141 |
DOCSTRING_PROTOTYPE_VAR: Final[str] = libclinic.normalize_snippet(""" |
| 142 |
PyDoc_VAR({c_basename}__doc__); |
| 143 |
""") |
| 144 |
DOCSTRING_PROTOTYPE_STRVAR: Final[str] = libclinic.normalize_snippet(""" |
| 145 |
PyDoc_STRVAR({c_basename}__doc__, |
| 146 |
{docstring}); |
| 147 |
""") |
| 148 |
GETSET_DOCSTRING_PROTOTYPE_STRVAR: Final[str] = libclinic.normalize_snippet(""" |
| 149 |
PyDoc_STRVAR({getset_basename}__doc__, |
| 150 |
{docstring}); |
| 151 |
#if defined({getset_basename}_DOCSTR) |
| 152 |
# undef {getset_basename}_DOCSTR |
| 153 |
#endif |
| 154 |
#define {getset_basename}_DOCSTR {getset_basename}__doc__ |
| 155 |
""") |
| 156 |
IMPL_DEFINITION_PROTOTYPE: Final[str] = libclinic.normalize_snippet(""" |
| 157 |
static {impl_return_type} |
| 158 |
{c_basename}_impl({impl_parameters}) |
| 159 |
""") |
| 160 |
METHODDEF_PROTOTYPE_DEFINE: Final[str] = libclinic.normalize_snippet(r""" |
| 161 |
#define {methoddef_name} \ |
| 162 |
{{"{name}", {methoddef_cast}{c_basename}{methoddef_cast_end}, {methoddef_flags}, {c_basename}__doc__}}, |
| 163 |
""") |
| 164 |
GETTERDEF_PROTOTYPE_DEFINE: Final[str] = libclinic.normalize_snippet(r""" |
| 165 |
#if !defined({getset_basename}_DOCSTR) |
| 166 |
# define {getset_basename}_DOCSTR NULL |
| 167 |
#endif |
| 168 |
#if defined({getset_name}_GETSETDEF) |
| 169 |
# undef {getset_name}_GETSETDEF |
| 170 |
# define {getset_name}_GETSETDEF {{"{name}", (getter){getset_basename}_get, (setter){getset_basename}_set, {getset_basename}_DOCSTR}}, |
| 171 |
#else |
| 172 |
# define {getset_name}_GETSETDEF {{"{name}", (getter){getset_basename}_get, NULL, {getset_basename}_DOCSTR}}, |
| 173 |
#endif |
| 174 |
""") |
| 175 |
SETTERDEF_PROTOTYPE_DEFINE: Final[str] = libclinic.normalize_snippet(r""" |
| 176 |
#if !defined({getset_basename}_DOCSTR) |
| 177 |
# define {getset_basename}_DOCSTR NULL |
| 178 |
#endif |
| 179 |
#if defined({getset_name}_GETSETDEF) |
| 180 |
# undef {getset_name}_GETSETDEF |
| 181 |
# define {getset_name}_GETSETDEF {{"{name}", (getter){getset_basename}_get, (setter){getset_basename}_set, {getset_basename}_DOCSTR}}, |
| 182 |
#else |
| 183 |
# define {getset_name}_GETSETDEF {{"{name}", NULL, (setter){getset_basename}_set, NULL}}, |
| 184 |
#endif |
| 185 |
""") |
| 186 |
METHODDEF_PROTOTYPE_IFNDEF: Final[str] = libclinic.normalize_snippet(""" |
| 187 |
#ifndef {methoddef_name} |
| 188 |
#define {methoddef_name} |
| 189 |
#endif /* !defined({methoddef_name}) */ |
| 190 |
""") |
| 191 |
|
| 192 |
|
| 193 |
class ParseArgsCodeGen: |
| 194 |
func: Function |
| 195 |
codegen: CodeGen |
| 196 |
limited_capi: bool = False |
| 197 |
|
| 198 |
# Function parameters |
| 199 |
parameters: list[Parameter] |
| 200 |
self_parameter_converter: self_converter |
| 201 |
converters: list[CConverter] |
| 202 |
|
| 203 |
# Is 'defining_class' used for the first parameter? |
| 204 |
requires_defining_class: bool |
| 205 |
|
| 206 |
# Use METH_FASTCALL calling convention? |
| 207 |
fastcall: bool |
| 208 |
|
| 209 |
# Declaration of the return variable (ex: "int return_value;") |
| 210 |
return_value_declaration: str |
| 211 |
|
| 212 |
# Calling convention (ex: "METH_NOARGS") |
| 213 |
flags: str |
| 214 |
|
| 215 |
# Variables declarations |
| 216 |
declarations: str |
| 217 |
|
| 218 |
pos_only: int = 0 |
| 219 |
min_pos: int = 0 |
| 220 |
max_pos: int = 0 |
| 221 |
min_kw_only: int = 0 |
| 222 |
varpos: Parameter | None = None |
| 223 |
|
| 224 |
docstring_prototype: str |
| 225 |
docstring_definition: str |
| 226 |
impl_prototype: str | None |
| 227 |
impl_definition: str |
| 228 |
methoddef_define: str |
| 229 |
parser_prototype: str |
| 230 |
parser_definition: str |
| 231 |
cpp_if: str |
| 232 |
cpp_endif: str |
| 233 |
methoddef_ifndef: str |
| 234 |
|
| 235 |
parser_body_fields: tuple[str, ...] |
| 236 |
|
| 237 |
def __init__(self, func: Function, codegen: CodeGen) -> None: |
| 238 |
self.func = func |
| 239 |
self.codegen = codegen |
| 240 |
|
| 241 |
self.parameters = list(self.func.parameters.values()) |
| 242 |
self_parameter = self.parameters.pop(0) |
| 243 |
if not isinstance(self_parameter.converter, self_converter): |
| 244 |
raise ValueError("the first parameter must use self_converter") |
| 245 |
self.self_parameter_converter = self_parameter.converter |
| 246 |
|
| 247 |
self.requires_defining_class = False |
| 248 |
if self.parameters and isinstance(self.parameters[0].converter, defining_class_converter): |
| 249 |
self.requires_defining_class = True |
| 250 |
del self.parameters[0] |
| 251 |
|
| 252 |
for i, p in enumerate(self.parameters): |
| 253 |
if p.is_vararg(): |
| 254 |
self.varpos = p |
| 255 |
del self.parameters[i] |
| 256 |
break |
| 257 |
|
| 258 |
self.converters = [p.converter for p in self.parameters] |
| 259 |
|
| 260 |
if self.func.critical_section: |
| 261 |
self.codegen.add_include('pycore_critical_section.h', |
| 262 |
'Py_BEGIN_CRITICAL_SECTION()') |
| 263 |
if self.func.disable_fastcall: |
| 264 |
self.fastcall = False |
| 265 |
else: |
| 266 |
self.fastcall = not self.is_new_or_init() |
| 267 |
|
| 268 |
self.pos_only = 0 |
| 269 |
self.min_pos = 0 |
| 270 |
self.max_pos = 0 |
| 271 |
self.min_kw_only = 0 |
| 272 |
for i, p in enumerate(self.parameters, 1): |
| 273 |
if p.is_keyword_only(): |
| 274 |
assert not p.is_positional_only() |
| 275 |
if not p.is_optional(): |
| 276 |
self.min_kw_only = i - self.max_pos |
| 277 |
else: |
| 278 |
self.max_pos = i |
| 279 |
if p.is_positional_only(): |
| 280 |
self.pos_only = i |
| 281 |
if not p.is_optional(): |
| 282 |
self.min_pos = i |
| 283 |
|
| 284 |
def is_new_or_init(self) -> bool: |
| 285 |
return self.func.kind.new_or_init |
| 286 |
|
| 287 |
def has_option_groups(self) -> bool: |
| 288 |
return (bool(self.parameters |
| 289 |
and (self.parameters[0].group or self.parameters[-1].group))) |
| 290 |
|
| 291 |
def use_meth_o(self) -> bool: |
| 292 |
return (len(self.parameters) == 1 |
| 293 |
and self.parameters[0].is_positional_only() |
| 294 |
and not self.converters[0].is_optional() |
| 295 |
and not self.varpos |
| 296 |
and not self.requires_defining_class |
| 297 |
and not self.is_new_or_init()) |
| 298 |
|
| 299 |
def use_simple_return(self) -> bool: |
| 300 |
return (self.func.return_converter.type == 'PyObject *' |
| 301 |
and not self.func.critical_section) |
| 302 |
|
| 303 |
def use_pyobject_self(self) -> bool: |
| 304 |
return self.self_parameter_converter.use_pyobject_self(self.func) |
| 305 |
|
| 306 |
def select_prototypes(self) -> None: |
| 307 |
self.docstring_prototype = '' |
| 308 |
self.docstring_definition = '' |
| 309 |
self.methoddef_define = METHODDEF_PROTOTYPE_DEFINE |
| 310 |
self.return_value_declaration = "PyObject *return_value = NULL;" |
| 311 |
|
| 312 |
if self.is_new_or_init() and not self.func.docstring: |
| 313 |
pass |
| 314 |
elif self.func.kind is GETTER: |
| 315 |
self.methoddef_define = GETTERDEF_PROTOTYPE_DEFINE |
| 316 |
if self.func.docstring: |
| 317 |
self.docstring_definition = GETSET_DOCSTRING_PROTOTYPE_STRVAR |
| 318 |
elif self.func.kind is SETTER: |
| 319 |
if self.func.docstring: |
| 320 |
fail("docstrings are only supported for @getter, not @setter") |
| 321 |
self.return_value_declaration = "int {return_value};" |
| 322 |
self.methoddef_define = SETTERDEF_PROTOTYPE_DEFINE |
| 323 |
else: |
| 324 |
self.docstring_prototype = DOCSTRING_PROTOTYPE_VAR |
| 325 |
self.docstring_definition = DOCSTRING_PROTOTYPE_STRVAR |
| 326 |
|
| 327 |
def init_limited_capi(self) -> None: |
| 328 |
self.limited_capi = self.codegen.limited_capi |
| 329 |
if self.limited_capi and ( |
| 330 |
(self.varpos and self.pos_only < len(self.parameters)) or |
| 331 |
(any(p.is_optional() for p in self.parameters) and |
| 332 |
any(p.is_keyword_only() and not p.is_optional() for p in self.parameters)) or |
| 333 |
any(c.broken_limited_capi for c in self.converters)): |
| 334 |
warn(f"Function {self.func.full_name} cannot use limited C API") |
| 335 |
self.limited_capi = False |
| 336 |
|
| 337 |
def parser_body( |
| 338 |
self, |
| 339 |
*fields: str, |
| 340 |
declarations: str = '' |
| 341 |
) -> None: |
| 342 |
lines = [self.parser_prototype] |
| 343 |
self.parser_body_fields = fields |
| 344 |
|
| 345 |
preamble = libclinic.normalize_snippet(""" |
| 346 |
{{ |
| 347 |
{return_value_declaration} |
| 348 |
{parser_declarations} |
| 349 |
{declarations} |
| 350 |
{initializers} |
| 351 |
""") + "\n" |
| 352 |
finale = libclinic.normalize_snippet(""" |
| 353 |
{modifications} |
| 354 |
{lock} |
| 355 |
{return_value} = {c_basename}_impl({impl_arguments}); |
| 356 |
{unlock} |
| 357 |
{return_conversion} |
| 358 |
{post_parsing} |
| 359 |
|
| 360 |
{exit_label} |
| 361 |
{cleanup} |
| 362 |
return return_value; |
| 363 |
}} |
| 364 |
""") |
| 365 |
for field in preamble, *fields, finale: |
| 366 |
lines.append(field) |
| 367 |
code = libclinic.linear_format("\n".join(lines), |
| 368 |
parser_declarations=self.declarations) |
| 369 |
self.parser_definition = code |
| 370 |
|
| 371 |
def parse_no_args(self) -> None: |
| 372 |
parser_code: list[str] | None |
| 373 |
simple_return = self.use_simple_return() |
| 374 |
if self.func.kind is GETTER: |
| 375 |
self.parser_prototype = PARSER_PROTOTYPE_GETTER |
| 376 |
parser_code = [] |
| 377 |
elif self.func.kind is SETTER: |
| 378 |
self.parser_prototype = PARSER_PROTOTYPE_SETTER |
| 379 |
parser_code = [] |
| 380 |
elif not self.requires_defining_class: |
| 381 |
# no self.parameters, METH_NOARGS |
| 382 |
self.flags = "METH_NOARGS" |
| 383 |
self.parser_prototype = PARSER_PROTOTYPE_NOARGS |
| 384 |
parser_code = [] |
| 385 |
else: |
| 386 |
assert self.fastcall |
| 387 |
|
| 388 |
self.flags = "METH_METHOD|METH_FASTCALL|METH_KEYWORDS" |
| 389 |
self.parser_prototype = PARSER_PROTOTYPE_DEF_CLASS |
| 390 |
return_error = ('return NULL;' if simple_return |
| 391 |
else 'goto exit;') |
| 392 |
parser_code = [libclinic.normalize_snippet(""" |
| 393 |
if (nargs || (kwnames && PyTuple_GET_SIZE(kwnames))) {{ |
| 394 |
PyErr_SetString(PyExc_TypeError, "{name}() takes no arguments"); |
| 395 |
%s |
| 396 |
}} |
| 397 |
""" % return_error, indent=4)] |
| 398 |
|
| 399 |
if simple_return: |
| 400 |
self.parser_definition = '\n'.join([ |
| 401 |
self.parser_prototype, |
| 402 |
'{{', |
| 403 |
*parser_code, |
| 404 |
' return {c_basename}_impl({impl_arguments});', |
| 405 |
'}}']) |
| 406 |
else: |
| 407 |
self.parser_body(*parser_code) |
| 408 |
|
| 409 |
def parse_one_arg(self) -> None: |
| 410 |
self.flags = "METH_O" |
| 411 |
|
| 412 |
if (isinstance(self.converters[0], object_converter) and |
| 413 |
self.converters[0].format_unit == 'O'): |
| 414 |
meth_o_prototype = METH_O_PROTOTYPE |
| 415 |
|
| 416 |
if self.use_simple_return() and self.use_pyobject_self(): |
| 417 |
# maps perfectly to METH_O, doesn't need a return converter. |
| 418 |
# so we skip making a parse function |
| 419 |
# and call directly into the impl function. |
| 420 |
self.impl_prototype = '' |
| 421 |
self.impl_definition = meth_o_prototype |
| 422 |
else: |
| 423 |
# SLIGHT HACK |
| 424 |
# use impl_parameters for the parser here! |
| 425 |
self.parser_prototype = meth_o_prototype |
| 426 |
self.parser_body() |
| 427 |
|
| 428 |
else: |
| 429 |
argname = 'arg' |
| 430 |
if self.parameters[0].name == argname: |
| 431 |
argname += '_' |
| 432 |
self.parser_prototype = libclinic.normalize_snippet(""" |
| 433 |
static PyObject * |
| 434 |
{c_basename}({self_type}{self_name}, PyObject *%s) |
| 435 |
""" % argname) |
| 436 |
|
| 437 |
displayname = self.parameters[0].get_displayname(0) |
| 438 |
parsearg: str | None |
| 439 |
parsearg = self.converters[0].parse_arg(argname, displayname, |
| 440 |
limited_capi=self.limited_capi) |
| 441 |
if parsearg is None: |
| 442 |
self.converters[0].use_converter() |
| 443 |
parsearg = """ |
| 444 |
if (!PyArg_Parse(%s, "{format_units}:{name}", {parse_arguments})) {{ |
| 445 |
goto exit; |
| 446 |
}} |
| 447 |
""" % argname |
| 448 |
|
| 449 |
parser_code = libclinic.normalize_snippet(parsearg, indent=4) |
| 450 |
self.parser_body(parser_code) |
| 451 |
|
| 452 |
def parse_option_groups(self) -> None: |
| 453 |
# positional parameters with option groups |
| 454 |
# (we have to generate lots of PyArg_ParseTuple calls |
| 455 |
# in a big switch statement) |
| 456 |
|
| 457 |
self.flags = "METH_VARARGS" |
| 458 |
self.parser_prototype = PARSER_PROTOTYPE_VARARGS |
| 459 |
parser_code = ' {option_group_parsing}' |
| 460 |
self.parser_body(parser_code) |
| 461 |
|
| 462 |
def _parse_vararg(self) -> str: |
| 463 |
assert self.varpos is not None |
| 464 |
c = self.varpos.converter |
| 465 |
assert isinstance(c, libclinic.converters.VarPosCConverter) |
| 466 |
return c.parse_vararg(pos_only=self.pos_only, |
| 467 |
min_pos=self.min_pos, |
| 468 |
max_pos=self.max_pos, |
| 469 |
fastcall=self.fastcall, |
| 470 |
limited_capi=self.limited_capi) |
| 471 |
|
| 472 |
def parse_pos_only(self) -> None: |
| 473 |
if self.fastcall: |
| 474 |
# positional-only, but no option groups |
| 475 |
# we only need one call to _PyArg_ParseStack |
| 476 |
|
| 477 |
self.flags = "METH_FASTCALL" |
| 478 |
self.parser_prototype = PARSER_PROTOTYPE_FASTCALL |
| 479 |
nargs = 'nargs' |
| 480 |
argname_fmt = 'args[%d]' |
| 481 |
else: |
| 482 |
# positional-only, but no option groups |
| 483 |
# we only need one call to PyArg_ParseTuple |
| 484 |
|
| 485 |
self.flags = "METH_VARARGS" |
| 486 |
self.parser_prototype = PARSER_PROTOTYPE_VARARGS |
| 487 |
if self.limited_capi: |
| 488 |
nargs = 'PyTuple_Size(args)' |
| 489 |
argname_fmt = 'PyTuple_GetItem(args, %d)' |
| 490 |
else: |
| 491 |
nargs = 'PyTuple_GET_SIZE(args)' |
| 492 |
argname_fmt = 'PyTuple_GET_ITEM(args, %d)' |
| 493 |
|
| 494 |
parser_code = [] |
| 495 |
max_args = NO_VARARG if self.varpos else self.max_pos |
| 496 |
if self.limited_capi: |
| 497 |
if nargs != 'nargs': |
| 498 |
nargs_def = f'Py_ssize_t nargs = {nargs};' |
| 499 |
parser_code.append(libclinic.normalize_snippet(nargs_def, indent=4)) |
| 500 |
nargs = 'nargs' |
| 501 |
if self.min_pos == max_args: |
| 502 |
pl = '' if self.min_pos == 1 else 's' |
| 503 |
parser_code.append(libclinic.normalize_snippet(f""" |
| 504 |
if ({nargs} != {self.min_pos}) {{{{ |
| 505 |
PyErr_Format(PyExc_TypeError, "{{name}} expected {self.min_pos} argument{pl}, got %zd", {nargs}); |
| 506 |
goto exit; |
| 507 |
}}}} |
| 508 |
""", |
| 509 |
indent=4)) |
| 510 |
else: |
| 511 |
if self.min_pos: |
| 512 |
pl = '' if self.min_pos == 1 else 's' |
| 513 |
parser_code.append(libclinic.normalize_snippet(f""" |
| 514 |
if ({nargs} < {self.min_pos}) {{{{ |
| 515 |
PyErr_Format(PyExc_TypeError, "{{name}} expected at least {self.min_pos} argument{pl}, got %zd", {nargs}); |
| 516 |
goto exit; |
| 517 |
}}}} |
| 518 |
""", |
| 519 |
indent=4)) |
| 520 |
if max_args != NO_VARARG: |
| 521 |
pl = '' if max_args == 1 else 's' |
| 522 |
parser_code.append(libclinic.normalize_snippet(f""" |
| 523 |
if ({nargs} > {max_args}) {{{{ |
| 524 |
PyErr_Format(PyExc_TypeError, "{{name}} expected at most {max_args} argument{pl}, got %zd", {nargs}); |
| 525 |
goto exit; |
| 526 |
}}}} |
| 527 |
""", |
| 528 |
indent=4)) |
| 529 |
elif self.min_pos or max_args != NO_VARARG: |
| 530 |
self.codegen.add_include('pycore_modsupport.h', |
| 531 |
'_PyArg_CheckPositional()') |
| 532 |
parser_code.append(libclinic.normalize_snippet(f""" |
| 533 |
if (!_PyArg_CheckPositional("{{name}}", {nargs}, {self.min_pos}, {max_args})) {{{{ |
| 534 |
goto exit; |
| 535 |
}}}} |
| 536 |
""", indent=4)) |
| 537 |
|
| 538 |
has_optional = False |
| 539 |
use_parser_code = True |
| 540 |
for i, p in enumerate(self.parameters): |
| 541 |
displayname = p.get_displayname(i+1) |
| 542 |
argname = argname_fmt % i |
| 543 |
parsearg: str | None |
| 544 |
parsearg = p.converter.parse_arg(argname, displayname, limited_capi=self.limited_capi) |
| 545 |
if parsearg is None: |
| 546 |
if self.varpos: |
| 547 |
raise ValueError( |
| 548 |
f"Using converter {p.converter} is not supported " |
| 549 |
f"in function with var-positional parameter") |
| 550 |
use_parser_code = False |
| 551 |
parser_code = [] |
| 552 |
break |
| 553 |
if has_optional or p.is_optional(): |
| 554 |
has_optional = True |
| 555 |
parser_code.append(libclinic.normalize_snippet(""" |
| 556 |
if (%s < %d) {{ |
| 557 |
goto skip_optional; |
| 558 |
}} |
| 559 |
""", indent=4) % (nargs, i + 1)) |
| 560 |
parser_code.append(libclinic.normalize_snippet(parsearg, indent=4)) |
| 561 |
|
| 562 |
if use_parser_code: |
| 563 |
if has_optional: |
| 564 |
parser_code.append("skip_optional:") |
| 565 |
if self.varpos: |
| 566 |
parser_code.append(libclinic.normalize_snippet(self._parse_vararg(), indent=4)) |
| 567 |
else: |
| 568 |
for parameter in self.parameters: |
| 569 |
parameter.converter.use_converter() |
| 570 |
|
| 571 |
if self.limited_capi: |
| 572 |
self.fastcall = False |
| 573 |
if self.fastcall: |
| 574 |
self.codegen.add_include('pycore_modsupport.h', |
| 575 |
'_PyArg_ParseStack()') |
| 576 |
parser_code = [libclinic.normalize_snippet(""" |
| 577 |
if (!_PyArg_ParseStack(args, nargs, "{format_units}:{name}", |
| 578 |
{parse_arguments})) {{ |
| 579 |
goto exit; |
| 580 |
}} |
| 581 |
""", indent=4)] |
| 582 |
else: |
| 583 |
self.flags = "METH_VARARGS" |
| 584 |
self.parser_prototype = PARSER_PROTOTYPE_VARARGS |
| 585 |
parser_code = [libclinic.normalize_snippet(""" |
| 586 |
if (!PyArg_ParseTuple(args, "{format_units}:{name}", |
| 587 |
{parse_arguments})) {{ |
| 588 |
goto exit; |
| 589 |
}} |
| 590 |
""", indent=4)] |
| 591 |
self.parser_body(*parser_code) |
| 592 |
|
| 593 |
def parse_general(self, clang: CLanguage) -> None: |
| 594 |
parsearg: str | None |
| 595 |
deprecated_positionals: dict[int, Parameter] = {} |
| 596 |
deprecated_keywords: dict[int, Parameter] = {} |
| 597 |
for i, p in enumerate(self.parameters): |
| 598 |
if p.deprecated_positional: |
| 599 |
deprecated_positionals[i] = p |
| 600 |
if p.deprecated_keyword: |
| 601 |
deprecated_keywords[i] = p |
| 602 |
|
| 603 |
has_optional_kw = ( |
| 604 |
max(self.pos_only, self.min_pos) + self.min_kw_only |
| 605 |
< len(self.converters) |
| 606 |
) |
| 607 |
|
| 608 |
use_parser_code = True |
| 609 |
if self.limited_capi: |
| 610 |
parser_code = [] |
| 611 |
use_parser_code = False |
| 612 |
self.fastcall = False |
| 613 |
else: |
| 614 |
self.codegen.add_include('pycore_modsupport.h', |
| 615 |
'_PyArg_UnpackKeywords()') |
| 616 |
if not self.varpos: |
| 617 |
nargs = "nargs" |
| 618 |
else: |
| 619 |
nargs = f"Py_MIN(nargs, {self.max_pos})" if self.max_pos else "0" |
| 620 |
|
| 621 |
if self.fastcall: |
| 622 |
self.flags = "METH_FASTCALL|METH_KEYWORDS" |
| 623 |
self.parser_prototype = PARSER_PROTOTYPE_FASTCALL_KEYWORDS |
| 624 |
self.declarations = declare_parser(self.func, codegen=self.codegen) |
| 625 |
self.declarations += "\nPyObject *argsbuf[%s];" % (len(self.converters) or 1) |
| 626 |
if self.varpos: |
| 627 |
self.declarations += "\nPyObject * const *fastargs;" |
| 628 |
argsname = 'fastargs' |
| 629 |
argname_fmt = 'fastargs[%d]' |
| 630 |
else: |
| 631 |
argsname = 'args' |
| 632 |
argname_fmt = 'args[%d]' |
| 633 |
if has_optional_kw: |
| 634 |
self.declarations += "\nPy_ssize_t noptargs = %s + (kwnames ? PyTuple_GET_SIZE(kwnames) : 0) - %d;" % (nargs, self.min_pos + self.min_kw_only) |
| 635 |
unpack_args = 'args, nargs, NULL, kwnames' |
| 636 |
else: |
| 637 |
# positional-or-keyword arguments |
| 638 |
self.flags = "METH_VARARGS|METH_KEYWORDS" |
| 639 |
self.parser_prototype = PARSER_PROTOTYPE_KEYWORD |
| 640 |
argsname = 'fastargs' |
| 641 |
argname_fmt = 'fastargs[%d]' |
| 642 |
self.declarations = declare_parser(self.func, codegen=self.codegen) |
| 643 |
self.declarations += "\nPyObject *argsbuf[%s];" % (len(self.converters) or 1) |
| 644 |
self.declarations += "\nPyObject * const *fastargs;" |
| 645 |
self.declarations += "\nPy_ssize_t nargs = PyTuple_GET_SIZE(args);" |
| 646 |
if has_optional_kw: |
| 647 |
self.declarations += "\nPy_ssize_t noptargs = %s + (kwargs ? PyDict_GET_SIZE(kwargs) : 0) - %d;" % (nargs, self.min_pos + self.min_kw_only) |
| 648 |
unpack_args = '_PyTuple_CAST(args)->ob_item, nargs, kwargs, NULL' |
| 649 |
parser_code = [libclinic.normalize_snippet(f""" |
| 650 |
{argsname} = _PyArg_UnpackKeywords({unpack_args}, &_parser, |
| 651 |
/*minpos*/ {self.min_pos}, /*maxpos*/ {self.max_pos}, /*minkw*/ {self.min_kw_only}, /*varpos*/ {1 if self.varpos else 0}, argsbuf); |
| 652 |
if (!{argsname}) {{{{ |
| 653 |
goto exit; |
| 654 |
}}}} |
| 655 |
""", indent=4)] |
| 656 |
|
| 657 |
if self.requires_defining_class: |
| 658 |
self.flags = 'METH_METHOD|' + self.flags |
| 659 |
self.parser_prototype = PARSER_PROTOTYPE_DEF_CLASS |
| 660 |
|
| 661 |
if use_parser_code: |
| 662 |
if deprecated_keywords: |
| 663 |
code = clang.deprecate_keyword_use(self.func, deprecated_keywords, |
| 664 |
argname_fmt, |
| 665 |
codegen=self.codegen, |
| 666 |
fastcall=self.fastcall) |
| 667 |
parser_code.append(code) |
| 668 |
|
| 669 |
add_label: str | None = None |
| 670 |
for i, p in enumerate(self.parameters): |
| 671 |
if isinstance(p.converter, defining_class_converter): |
| 672 |
raise ValueError("defining_class should be the first " |
| 673 |
"parameter (after clang)") |
| 674 |
displayname = p.get_displayname(i+1) |
| 675 |
parsearg = p.converter.parse_arg(argname_fmt % i, displayname, limited_capi=self.limited_capi) |
| 676 |
if parsearg is None: |
| 677 |
parser_code = [] |
| 678 |
use_parser_code = False |
| 679 |
break |
| 680 |
if add_label and (i == self.pos_only or i == self.max_pos): |
| 681 |
parser_code.append("%s:" % add_label) |
| 682 |
add_label = None |
| 683 |
if not p.is_optional(): |
| 684 |
parser_code.append(libclinic.normalize_snippet(parsearg, indent=4)) |
| 685 |
elif i < self.pos_only: |
| 686 |
add_label = 'skip_optional_posonly' |
| 687 |
parser_code.append(libclinic.normalize_snippet(""" |
| 688 |
if (nargs < %d) {{ |
| 689 |
goto %s; |
| 690 |
}} |
| 691 |
""" % (i + 1, add_label), indent=4)) |
| 692 |
if has_optional_kw: |
| 693 |
parser_code.append(libclinic.normalize_snippet(""" |
| 694 |
noptargs--; |
| 695 |
""", indent=4)) |
| 696 |
parser_code.append(libclinic.normalize_snippet(parsearg, indent=4)) |
| 697 |
else: |
| 698 |
if i < self.max_pos: |
| 699 |
label = 'skip_optional_pos' |
| 700 |
first_opt = max(self.min_pos, self.pos_only) |
| 701 |
else: |
| 702 |
label = 'skip_optional_kwonly' |
| 703 |
first_opt = self.max_pos + self.min_kw_only |
| 704 |
if i == first_opt: |
| 705 |
add_label = label |
| 706 |
parser_code.append(libclinic.normalize_snippet(""" |
| 707 |
if (!noptargs) {{ |
| 708 |
goto %s; |
| 709 |
}} |
| 710 |
""" % add_label, indent=4)) |
| 711 |
if i + 1 == len(self.parameters): |
| 712 |
parser_code.append(libclinic.normalize_snippet(parsearg, indent=4)) |
| 713 |
else: |
| 714 |
add_label = label |
| 715 |
parser_code.append(libclinic.normalize_snippet(""" |
| 716 |
if (%s) {{ |
| 717 |
""" % (argname_fmt % i), indent=4)) |
| 718 |
parser_code.append(libclinic.normalize_snippet(parsearg, indent=8)) |
| 719 |
parser_code.append(libclinic.normalize_snippet(""" |
| 720 |
if (!--noptargs) {{ |
| 721 |
goto %s; |
| 722 |
}} |
| 723 |
}} |
| 724 |
""" % add_label, indent=4)) |
| 725 |
|
| 726 |
if use_parser_code: |
| 727 |
if add_label: |
| 728 |
parser_code.append("%s:" % add_label) |
| 729 |
if self.varpos: |
| 730 |
parser_code.append(libclinic.normalize_snippet(self._parse_vararg(), indent=4)) |
| 731 |
else: |
| 732 |
for parameter in self.parameters: |
| 733 |
parameter.converter.use_converter() |
| 734 |
|
| 735 |
self.declarations = declare_parser(self.func, codegen=self.codegen, |
| 736 |
hasformat=True) |
| 737 |
if self.limited_capi: |
| 738 |
# positional-or-keyword arguments |
| 739 |
assert not self.fastcall |
| 740 |
self.flags = "METH_VARARGS|METH_KEYWORDS" |
| 741 |
self.parser_prototype = PARSER_PROTOTYPE_KEYWORD |
| 742 |
parser_code = [libclinic.normalize_snippet(""" |
| 743 |
if (!PyArg_ParseTupleAndKeywords(args, kwargs, "{format_units}:{name}", _keywords, |
| 744 |
{parse_arguments})) |
| 745 |
goto exit; |
| 746 |
""", indent=4)] |
| 747 |
self.declarations = "static char *_keywords[] = {{{keywords_c} NULL}};" |
| 748 |
if deprecated_positionals or deprecated_keywords: |
| 749 |
self.declarations += "\nPy_ssize_t nargs = PyTuple_Size(args);" |
| 750 |
|
| 751 |
elif self.fastcall: |
| 752 |
self.codegen.add_include('pycore_modsupport.h', |
| 753 |
'_PyArg_ParseStackAndKeywords()') |
| 754 |
parser_code = [libclinic.normalize_snippet(""" |
| 755 |
if (!_PyArg_ParseStackAndKeywords(args, nargs, kwnames, &_parser{parse_arguments_comma} |
| 756 |
{parse_arguments})) {{ |
| 757 |
goto exit; |
| 758 |
}} |
| 759 |
""", indent=4)] |
| 760 |
else: |
| 761 |
self.codegen.add_include('pycore_modsupport.h', |
| 762 |
'_PyArg_ParseTupleAndKeywordsFast()') |
| 763 |
parser_code = [libclinic.normalize_snippet(""" |
| 764 |
if (!_PyArg_ParseTupleAndKeywordsFast(args, kwargs, &_parser, |
| 765 |
{parse_arguments})) {{ |
| 766 |
goto exit; |
| 767 |
}} |
| 768 |
""", indent=4)] |
| 769 |
if deprecated_positionals or deprecated_keywords: |
| 770 |
self.declarations += "\nPy_ssize_t nargs = PyTuple_GET_SIZE(args);" |
| 771 |
if deprecated_keywords: |
| 772 |
code = clang.deprecate_keyword_use(self.func, deprecated_keywords, |
| 773 |
codegen=self.codegen, |
| 774 |
fastcall=self.fastcall) |
| 775 |
parser_code.append(code) |
| 776 |
|
| 777 |
if deprecated_positionals: |
| 778 |
code = clang.deprecate_positional_use(self.func, deprecated_positionals) |
| 779 |
# Insert the deprecation code before parameter parsing. |
| 780 |
parser_code.insert(0, code) |
| 781 |
|
| 782 |
assert self.parser_prototype is not None |
| 783 |
self.parser_body(*parser_code, declarations=self.declarations) |
| 784 |
|
| 785 |
def copy_includes(self) -> None: |
| 786 |
# Copy includes from parameters to Clinic after parse_arg() |
| 787 |
# has been called above. |
| 788 |
converters = self.converters |
| 789 |
if self.varpos: |
| 790 |
converters = converters + [self.varpos.converter] |
| 791 |
for converter in converters: |
| 792 |
for include in converter.get_includes(): |
| 793 |
self.codegen.add_include( |
| 794 |
include.filename, |
| 795 |
include.reason, |
| 796 |
condition=include.condition) |
| 797 |
|
| 798 |
def handle_new_or_init(self) -> None: |
| 799 |
self.methoddef_define = '' |
| 800 |
|
| 801 |
if self.func.kind is METHOD_NEW: |
| 802 |
self.parser_prototype = PARSER_PROTOTYPE_KEYWORD |
| 803 |
else: |
| 804 |
self.return_value_declaration = "int return_value = -1;" |
| 805 |
self.parser_prototype = PARSER_PROTOTYPE_KEYWORD___INIT__ |
| 806 |
|
| 807 |
fields: list[str] = list(self.parser_body_fields) |
| 808 |
parses_positional = 'METH_NOARGS' not in self.flags |
| 809 |
parses_keywords = 'METH_KEYWORDS' in self.flags |
| 810 |
if parses_keywords: |
| 811 |
assert parses_positional |
| 812 |
|
| 813 |
if self.requires_defining_class: |
| 814 |
raise ValueError("Slot methods cannot access their defining class.") |
| 815 |
|
| 816 |
if not parses_keywords: |
| 817 |
self.declarations = '{base_type_ptr}' |
| 818 |
self.codegen.add_include('pycore_modsupport.h', |
| 819 |
'_PyArg_NoKeywords()') |
| 820 |
fields.insert(0, libclinic.normalize_snippet(""" |
| 821 |
if ({self_type_check}!_PyArg_NoKeywords("{name}", kwargs)) {{ |
| 822 |
goto exit; |
| 823 |
}} |
| 824 |
""", indent=4)) |
| 825 |
if not parses_positional: |
| 826 |
self.codegen.add_include('pycore_modsupport.h', |
| 827 |
'_PyArg_NoPositional()') |
| 828 |
fields.insert(0, libclinic.normalize_snippet(""" |
| 829 |
if ({self_type_check}!_PyArg_NoPositional("{name}", args)) {{ |
| 830 |
goto exit; |
| 831 |
}} |
| 832 |
""", indent=4)) |
| 833 |
|
| 834 |
self.parser_body(*fields, declarations=self.declarations) |
| 835 |
|
| 836 |
def process_methoddef(self, clang: CLanguage) -> None: |
| 837 |
methoddef_cast_end = "" |
| 838 |
if self.flags in ('METH_NOARGS', 'METH_O', 'METH_VARARGS'): |
| 839 |
methoddef_cast = "(PyCFunction)" |
| 840 |
elif self.func.kind is GETTER: |
| 841 |
methoddef_cast = "" # This should end up unused |
| 842 |
elif self.limited_capi: |
| 843 |
methoddef_cast = "(PyCFunction)(void(*)(void))" |
| 844 |
else: |
| 845 |
methoddef_cast = "_PyCFunction_CAST(" |
| 846 |
methoddef_cast_end = ")" |
| 847 |
|
| 848 |
if self.func.methoddef_flags: |
| 849 |
self.flags += '|' + self.func.methoddef_flags |
| 850 |
|
| 851 |
self.methoddef_define = self.methoddef_define.replace('{methoddef_flags}', self.flags) |
| 852 |
self.methoddef_define = self.methoddef_define.replace('{methoddef_cast}', methoddef_cast) |
| 853 |
self.methoddef_define = self.methoddef_define.replace('{methoddef_cast_end}', methoddef_cast_end) |
| 854 |
|
| 855 |
self.methoddef_ifndef = '' |
| 856 |
conditional = clang.cpp.condition() |
| 857 |
if not conditional: |
| 858 |
self.cpp_if = self.cpp_endif = '' |
| 859 |
else: |
| 860 |
self.cpp_if = "#if " + conditional |
| 861 |
self.cpp_endif = "#endif /* " + conditional + " */" |
| 862 |
|
| 863 |
if self.methoddef_define and self.codegen.add_ifndef_symbol(self.func.full_name): |
| 864 |
self.methoddef_ifndef = METHODDEF_PROTOTYPE_IFNDEF |
| 865 |
|
| 866 |
def finalize(self, clang: CLanguage) -> None: |
| 867 |
# add ';' to the end of self.parser_prototype and self.impl_prototype |
| 868 |
# (they mustn't be None, but they could be an empty string.) |
| 869 |
assert self.parser_prototype is not None |
| 870 |
if self.parser_prototype: |
| 871 |
assert not self.parser_prototype.endswith(';') |
| 872 |
self.parser_prototype += ';' |
| 873 |
|
| 874 |
if self.impl_prototype is None: |
| 875 |
self.impl_prototype = self.impl_definition |
| 876 |
if self.impl_prototype: |
| 877 |
self.impl_prototype += ";" |
| 878 |
|
| 879 |
self.parser_definition = self.parser_definition.replace("{return_value_declaration}", self.return_value_declaration) |
| 880 |
|
| 881 |
compiler_warning = clang.compiler_deprecated_warning(self.func, self.parameters) |
| 882 |
if compiler_warning: |
| 883 |
self.parser_definition = compiler_warning + "\n\n" + self.parser_definition |
| 884 |
|
| 885 |
def create_template_dict(self) -> dict[str, str]: |
| 886 |
d = { |
| 887 |
"docstring_prototype" : self.docstring_prototype, |
| 888 |
"docstring_definition" : self.docstring_definition, |
| 889 |
"impl_prototype" : self.impl_prototype, |
| 890 |
"methoddef_define" : self.methoddef_define, |
| 891 |
"parser_prototype" : self.parser_prototype, |
| 892 |
"parser_definition" : self.parser_definition, |
| 893 |
"impl_definition" : self.impl_definition, |
| 894 |
"cpp_if" : self.cpp_if, |
| 895 |
"cpp_endif" : self.cpp_endif, |
| 896 |
"methoddef_ifndef" : self.methoddef_ifndef, |
| 897 |
} |
| 898 |
|
| 899 |
# make sure we didn't forget to assign something, |
| 900 |
# and wrap each non-empty value in \n's |
| 901 |
d2 = {} |
| 902 |
for name, value in d.items(): |
| 903 |
assert value is not None, "got a None value for template " + repr(name) |
| 904 |
if value: |
| 905 |
value = '\n' + value + '\n' |
| 906 |
d2[name] = value |
| 907 |
return d2 |
| 908 |
|
| 909 |
def parse_args(self, clang: CLanguage) -> dict[str, str]: |
| 910 |
self.select_prototypes() |
| 911 |
self.init_limited_capi() |
| 912 |
|
| 913 |
self.flags = "" |
| 914 |
self.declarations = "" |
| 915 |
self.parser_prototype = "" |
| 916 |
self.parser_definition = "" |
| 917 |
self.impl_prototype = None |
| 918 |
self.impl_definition = IMPL_DEFINITION_PROTOTYPE |
| 919 |
|
| 920 |
# parser_body_fields remembers the fields passed in to the |
| 921 |
# previous call to parser_body. this is used for an awful hack. |
| 922 |
self.parser_body_fields: tuple[str, ...] = () |
| 923 |
|
| 924 |
if not self.parameters and not self.varpos: |
| 925 |
self.parse_no_args() |
| 926 |
elif self.use_meth_o(): |
| 927 |
self.parse_one_arg() |
| 928 |
elif self.has_option_groups(): |
| 929 |
self.parse_option_groups() |
| 930 |
elif (not self.requires_defining_class |
| 931 |
and self.pos_only == len(self.parameters)): |
| 932 |
self.parse_pos_only() |
| 933 |
else: |
| 934 |
self.parse_general(clang) |
| 935 |
|
| 936 |
self.copy_includes() |
| 937 |
if self.is_new_or_init(): |
| 938 |
self.handle_new_or_init() |
| 939 |
self.process_methoddef(clang) |
| 940 |
self.finalize(clang) |
| 941 |
|
| 942 |
return self.create_template_dict() |