unspecified = "unspecified"

unknown = "unknown"

def __repr__(self) -> str:

*args: object,

fail: Literal[True],

filename: str | None = None,

line_number: int | None = None,

*args: object,

fail: Literal[False] = False,

filename: str | None = None,

line_number: int | None = None,

*args: object,

fail: bool = False,

filename: str | None = None,

line_number: int | None = None,

) -> None:

joined = " ".join([str(a) for a in args])

error = ClinicError(joined, filename=filename, lineno=line_number)

if fail:

raise error

else:

*args: object,

filename: str | None = None,

line_number: int | None = None,

) -> None:

*args: object,

filename: str | None = None,

line_number: int | None = None,

) -> NoReturn:

def __init__(self) -> None:

# The C statements to declare variables.

# Should be full lines with \n eol characters.

self.declarations: list[str] = []

# The C statements required to initialize the variables before the parse call.

# Should be full lines with \n eol characters.

self.initializers: list[str] = []

# The C statements needed to dynamically modify the values

# parsed by the parse call, before calling the impl.

self.modifications: list[str] = []

# The entries for the "keywords" array for PyArg_ParseTuple.

# Should be individual strings representing the names.

self.keywords: list[str] = []

# The "format units" for PyArg_ParseTuple.

# Should be individual strings that will get

self.format_units: list[str] = []

# The varargs arguments for PyArg_ParseTuple.

self.parse_arguments: list[str] = []

# The parameter declarations for the impl function.

self.impl_parameters: list[str] = []

# The arguments to the impl function at the time it's called.

self.impl_arguments: list[str] = []

# For return converters: the name of the variable that

# should receive the value returned by the impl.

self.return_value = "return_value"

# For return converters: the code to convert the return

# value from the parse function. This is also where

# you should check the _return_value for errors, and

# "goto exit" if there are any.

self.return_conversion: list[str] = []

self.converter_retval = "_return_value"

# The C statements required to do some operations

# after the end of parsing but before cleaning up.

# These operations may be, for example, memory deallocations which

# can only be done without any error happening during argument parsing.

self.post_parsing: list[str] = []

# The C statements required to clean up after the impl call.

self.cleanup: list[str] = []

# The C statements to generate critical sections (per-object locking).

self.lock: list[str] = []

start_line = ""

body_prefix = ""

stop_line = ""

checksum_line = ""

def __init__(self, filename: str) -> None:

self.filename = filename

@abc.abstractmethod

def render(

self,

clinic: Clinic,

signatures: Iterable[Module | Class | Function]

) -> str:

...

def parse_line(self, line: str) -> None:

...

def validate(self) -> None:

def assert_only_one(

attr: str,

*additional_fields: str

) -> None:

"""

fields = ['dsl_name']

fields.extend(additional_fields)

line: str = getattr(self, attr)

fcf = libclinic.FormatCounterFormatter()

fcf.format(line)

def local_fail(should_be_there_but_isnt: bool) -> None:

if should_be_there_but_isnt:

fail("{} {} must contain {{{}}} exactly once!".format(

self.__class__.__name__, attr, name))

else:

fail("{} {} must not contain {{{}}}!".format(

self.__class__.__name__, attr, name))

for name, count in fcf.counts.items():

if name in fields:

if count > 1:

local_fail(True)

else:

local_fail(False)

for name in fields:

if fcf.counts.get(name) != 1:

local_fail(True)

assert_only_one('start_line')

assert_only_one('stop_line')

field = "arguments" if "{arguments}" in self.checksum_line else "checksum"

language = 'Python'

start_line = "#/*[{dsl_name} input]"

body_prefix = "#"

stop_line = "#[{dsl_name} start generated code]*/"

l: Sequence[Iterable[Parameter]]

) -> Iterator[ParamTuple]:

"""

yield tuple()

accumulator: list[Parameter] = []

for group in reversed(l):

accumulator = list(group) + accumulator

l: Sequence[Iterable[Parameter]]

) -> Iterator[ParamTuple]:

"""

yield tuple()

accumulator: list[Parameter] = []

for group in l:

accumulator.extend(group)

left: Sequence[Iterable[Parameter]],

required: Iterable[Parameter],

right: Sequence[Iterable[Parameter]]

) -> tuple[ParamTuple, ...]:

"""

required = tuple(required)

if not required:

if left:

raise ValueError("required is empty but left is not")

accumulator: list[ParamTuple] = []

counts = set()

for r in permute_right_option_groups(right):

for l in permute_left_option_groups(left):

t = l + required + r

if len(t) in counts:

continue

counts.add(len(t))

accumulator.append(t)

accumulator.sort(key=len)

f: Function,

*,

hasformat: bool = False,

clinic: Clinic,

limited_capi: bool,

) -> str:

"""

if hasformat:

fname = ''

format_ = '.format = "{format_units}:{name}",'

else:

fname = '.fname = "{name}",'

format_ = ''

num_keywords = len([

p for p in f.parameters.values()

if not p.is_positional_only() and not p.is_vararg()

])

if limited_capi:

declarations = """

elif num_keywords == 0:

declarations = """

else:

declarations = """

""" % num_keywords

condition = '#if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)'

clinic.add_include('pycore_gc.h', 'PyGC_Head', condition=condition)

clinic.add_include('pycore_runtime.h', '_Py_ID()', condition=condition)

declarations += """

""" % (format_ or fname)

body_prefix = "#"

language = 'C'

start_line = "/*[{dsl_name} input]"

body_prefix = ""

stop_line = "[{dsl_name} start generated code]*/"

checksum_line = "/*[{dsl_name} end generated code: {arguments}]*/"

NO_VARARG: Final[str] = "PY_SSIZE_T_MAX"

PARSER_PROTOTYPE_KEYWORD: Final[str] = libclinic.normalize_snippet("""

""")

PARSER_PROTOTYPE_KEYWORD___INIT__: Final[str] = libclinic.normalize_snippet("""

""")

PARSER_PROTOTYPE_VARARGS: Final[str] = libclinic.normalize_snippet("""

""")

PARSER_PROTOTYPE_FASTCALL: Final[str] = libclinic.normalize_snippet("""

""")

PARSER_PROTOTYPE_FASTCALL_KEYWORDS: Final[str] = libclinic.normalize_snippet("""

""")

PARSER_PROTOTYPE_DEF_CLASS: Final[str] = libclinic.normalize_snippet("""

""")

PARSER_PROTOTYPE_NOARGS: Final[str] = libclinic.normalize_snippet("""

""")

PARSER_PROTOTYPE_GETTER: Final[str] = libclinic.normalize_snippet("""

""")

PARSER_PROTOTYPE_SETTER: Final[str] = libclinic.normalize_snippet("""

""")

METH_O_PROTOTYPE: Final[str] = libclinic.normalize_snippet("""

""")

DOCSTRING_PROTOTYPE_VAR: Final[str] = libclinic.normalize_snippet("""

""")

DOCSTRING_PROTOTYPE_STRVAR: Final[str] = libclinic.normalize_snippet("""

""")

GETSET_DOCSTRING_PROTOTYPE_STRVAR: Final[str] = libclinic.normalize_snippet("""

""")

IMPL_DEFINITION_PROTOTYPE: Final[str] = libclinic.normalize_snippet("""

""")

METHODDEF_PROTOTYPE_DEFINE: Final[str] = libclinic.normalize_snippet(r"""

""")

GETTERDEF_PROTOTYPE_DEFINE: Final[str] = libclinic.normalize_snippet(r"""

""")

SETTERDEF_PROTOTYPE_DEFINE: Final[str] = libclinic.normalize_snippet(r"""

""")

METHODDEF_PROTOTYPE_IFNDEF: Final[str] = libclinic.normalize_snippet("""

""")

COMPILER_DEPRECATION_WARNING_PROTOTYPE: Final[str] = r"""

DEPRECATION_WARNING_PROTOTYPE: Final[str] = r"""

def __init__(self, filename: str) -> None:

super().__init__(filename)

self.cpp = libclinic.cpp.Monitor(filename)

def parse_line(self, line: str) -> None:

self.cpp.writeline(line)

def render(

self,

clinic: Clinic,

signatures: Iterable[Module | Class | Function]

) -> str:

function = None

for o in signatures:

if isinstance(o, Function):

if function:

fail("You may specify at most one function per block.\nFound a block containing at least two:\n\t" + repr(function) + " and " + repr(o))

function = o

return self.render_function(clinic, function)

def compiler_deprecated_warning(

self,

func: Function,

parameters: list[Parameter],

) -> str | None:

minversion: VersionTuple | None = None

for p in parameters:

for version in p.deprecated_positional, p.deprecated_keyword:

if version and (not minversion or minversion > version):

minversion = version

if not minversion:

return None

# Format the preprocessor warning and error messages.

assert isinstance(self.cpp.filename, str)

message = f"Update the clinic input of {func.full_name!r}."

code = self.COMPILER_DEPRECATION_WARNING_PROTOTYPE.format(

major=minversion[0],

minor=minversion[1],

message=libclinic.c_repr(message),

)

return libclinic.normalize_snippet(code)

def deprecate_positional_use(

self,

func: Function,

params: dict[int, Parameter],

) -> str:

assert len(params) > 0

first_pos = next(iter(params))

last_pos = next(reversed(params))

# Format the deprecation message.

if len(params) == 1:

condition = f"nargs == {first_pos+1}"

amount = f"{first_pos+1} " if first_pos else ""

pl = "s"

else:

condition = f"nargs > {first_pos} && nargs <= {last_pos+1}"

amount = f"more than {first_pos} " if first_pos else ""

pl = "s" if first_pos != 1 else ""

message = (

f"Passing {amount}positional argument{pl} to "

f"{func.fulldisplayname}() is deprecated."

)

for (major, minor), group in itertools.groupby(

params.values(), key=attrgetter("deprecated_positional")

):

names = [repr(p.name) for p in group]

pstr = libclinic.pprint_words(names)

if len(names) == 1:

message += (

f" Parameter {pstr} will become a keyword-only parameter "

f"in Python {major}.{minor}."

)

else:

message += (

f" Parameters {pstr} will become keyword-only parameters "

f"in Python {major}.{minor}."

)

# Append deprecation warning to docstring.

docstring = textwrap.fill(f"Note: {message}")

func.docstring += f"\n\n{docstring}\n"

# Format and return the code block.

code = self.DEPRECATION_WARNING_PROTOTYPE.format(

condition=condition,

errcheck="",

message=libclinic.wrapped_c_string_literal(message, width=64,

subsequent_indent=20),

)

return libclinic.normalize_snippet(code, indent=4)

def deprecate_keyword_use(

self,

func: Function,

params: dict[int, Parameter],

argname_fmt: str | None,

*,

fastcall: bool,

limited_capi: bool,

clinic: Clinic,

) -> str:

assert len(params) > 0

last_param = next(reversed(params.values()))

# Format the deprecation message.

containscheck = ""

conditions = []

for i, p in params.items():

if p.is_optional():

if argname_fmt:

conditions.append(f"nargs < {i+1} && {argname_fmt % i}")

elif fastcall:

conditions.append(f"nargs < {i+1} && PySequence_Contains(kwnames, &_Py_ID({p.name}))")

containscheck = "PySequence_Contains"

clinic.add_include('pycore_runtime.h', '_Py_ID()')

else:

conditions.append(f"nargs < {i+1} && PyDict_Contains(kwargs, &_Py_ID({p.name}))")

containscheck = "PyDict_Contains"

clinic.add_include('pycore_runtime.h', '_Py_ID()')

else:

conditions = [f"nargs < {i+1}"]

condition = ") || (".join(conditions)

if len(conditions) > 1:

condition = f"(({condition}))"

if last_param.is_optional():

if fastcall:

if limited_capi:

condition = f"kwnames && PyTuple_Size(kwnames) && {condition}"

else:

condition = f"kwnames && PyTuple_GET_SIZE(kwnames) && {condition}"

else:

if limited_capi:

condition = f"kwargs && PyDict_Size(kwargs) && {condition}"

else:

condition = f"kwargs && PyDict_GET_SIZE(kwargs) && {condition}"

names = [repr(p.name) for p in params.values()]

pstr = libclinic.pprint_words(names)

pl = 's' if len(params) != 1 else ''

message = (

f"Passing keyword argument{pl} {pstr} to "

f"{func.fulldisplayname}() is deprecated."

)

for (major, minor), group in itertools.groupby(

params.values(), key=attrgetter("deprecated_keyword")

):

names = [repr(p.name) for p in group]

pstr = libclinic.pprint_words(names)

pl = 's' if len(names) != 1 else ''

message += (

f" Parameter{pl} {pstr} will become positional-only "

f"in Python {major}.{minor}."

)

if containscheck:

errcheck = f"""

else:

errcheck = ""

if argname_fmt:

# Append deprecation warning to docstring.

docstring = textwrap.fill(f"Note: {message}")

func.docstring += f"\n\n{docstring}\n"

# Format and return the code block.

code = self.DEPRECATION_WARNING_PROTOTYPE.format(

condition=condition,

errcheck=errcheck,

message=libclinic.wrapped_c_string_literal(message, width=64,

subsequent_indent=20),

)

return libclinic.normalize_snippet(code, indent=4)

def output_templates(

self,

f: Function,

clinic: Clinic

) -> dict[str, str]:

parameters = list(f.parameters.values())

assert parameters

first_param = parameters.pop(0)

assert isinstance(first_param.converter, self_converter)

requires_defining_class = False

if parameters and isinstance(parameters[0].converter, defining_class_converter):

requires_defining_class = True

del parameters[0]

converters = [p.converter for p in parameters]

if f.critical_section:

clinic.add_include('pycore_critical_section.h', 'Py_BEGIN_CRITICAL_SECTION()')

has_option_groups = parameters and (parameters[0].group or parameters[-1].group)

simple_return = (f.return_converter.type == 'PyObject *'

and not f.critical_section)

new_or_init = f.kind.new_or_init

vararg: int | str = self.NO_VARARG

pos_only = min_pos = max_pos = min_kw_only = pseudo_args = 0

for i, p in enumerate(parameters, 1):

if p.is_keyword_only():

assert not p.is_positional_only()

if not p.is_optional():

min_kw_only = i - max_pos

elif p.is_vararg():

pseudo_args += 1

vararg = i - 1

else:

if vararg == self.NO_VARARG:

max_pos = i

if p.is_positional_only():

pos_only = i

if not p.is_optional():

min_pos = i

meth_o = (len(parameters) == 1 and

parameters[0].is_positional_only() and

not converters[0].is_optional() and

not requires_defining_class and

not new_or_init)

# we have to set these things before we're done:

#

# docstring_prototype

# docstring_definition

# impl_prototype

# methoddef_define

# parser_prototype

# parser_definition

# impl_definition

# cpp_if

# cpp_endif

# methoddef_ifndef

return_value_declaration = "PyObject *return_value = NULL;"

methoddef_define = self.METHODDEF_PROTOTYPE_DEFINE

if new_or_init and not f.docstring:

docstring_prototype = docstring_definition = ''

elif f.kind is GETTER:

methoddef_define = self.GETTERDEF_PROTOTYPE_DEFINE

if f.docstring:

docstring_prototype = ''

docstring_definition = self.GETSET_DOCSTRING_PROTOTYPE_STRVAR

else:

docstring_prototype = docstring_definition = ''

elif f.kind is SETTER:

if f.docstring:

fail("docstrings are only supported for @getter, not @setter")

return_value_declaration = "int {return_value};"

methoddef_define = self.SETTERDEF_PROTOTYPE_DEFINE

docstring_prototype = docstring_definition = ''

else:

docstring_prototype = self.DOCSTRING_PROTOTYPE_VAR

docstring_definition = self.DOCSTRING_PROTOTYPE_STRVAR

impl_definition = self.IMPL_DEFINITION_PROTOTYPE

impl_prototype = parser_prototype = parser_definition = None

# parser_body_fields remembers the fields passed in to the

# previous call to parser_body. this is used for an awful hack.

parser_body_fields: tuple[str, ...] = ()

def parser_body(

prototype: str,

*fields: str,

declarations: str = ''

) -> str:

nonlocal parser_body_fields

lines = []

lines.append(prototype)

parser_body_fields = fields

preamble = libclinic.normalize_snippet("""

""") + "\n"

finale = libclinic.normalize_snippet("""

""")

for field in preamble, *fields, finale:

lines.append(field)

return libclinic.linear_format("\n".join(lines),

parser_declarations=declarations)

fastcall = not new_or_init

limited_capi = clinic.limited_capi

if limited_capi and (pseudo_args or

(any(p.is_optional() for p in parameters) and

any(p.is_keyword_only() and not p.is_optional() for p in parameters)) or

any(c.broken_limited_capi for c in converters)):

warn(f"Function {f.full_name} cannot use limited C API")

limited_capi = False

parsearg: str | None

if not parameters:

parser_code: list[str] | None

if f.kind is GETTER:

flags = "" # This should end up unused

parser_prototype = self.PARSER_PROTOTYPE_GETTER

parser_code = []

elif f.kind is SETTER:

flags = ""

parser_prototype = self.PARSER_PROTOTYPE_SETTER

parser_code = []

elif not requires_defining_class:

# no parameters, METH_NOARGS

flags = "METH_NOARGS"

parser_prototype = self.PARSER_PROTOTYPE_NOARGS

parser_code = []

else:

assert fastcall

flags = "METH_METHOD|METH_FASTCALL|METH_KEYWORDS"

parser_prototype = self.PARSER_PROTOTYPE_DEF_CLASS

return_error = ('return NULL;' if simple_return

else 'goto exit;')

parser_code = [libclinic.normalize_snippet("""

""" % return_error, indent=4)]

if simple_return:

parser_definition = '\n'.join([

parser_prototype,

'{{',

*parser_code,

' return {c_basename}_impl({impl_arguments});',

'}}'])

else:

parser_definition = parser_body(parser_prototype, *parser_code)

elif meth_o:

flags = "METH_O"

if (isinstance(converters[0], object_converter) and

converters[0].format_unit == 'O'):

meth_o_prototype = self.METH_O_PROTOTYPE

if simple_return:

# maps perfectly to METH_O, doesn't need a return converter.

# so we skip making a parse function

# and call directly into the impl function.

impl_prototype = parser_prototype = parser_definition = ''

impl_definition = meth_o_prototype

else:

# SLIGHT HACK

# use impl_parameters for the parser here!

parser_prototype = meth_o_prototype

parser_definition = parser_body(parser_prototype)

else:

argname = 'arg'

if parameters[0].name == argname:

argname += '_'

parser_prototype = libclinic.normalize_snippet("""

""" % argname)

displayname = parameters[0].get_displayname(0)

parsearg = converters[0].parse_arg(argname, displayname, limited_capi=limited_capi)

if parsearg is None:

parsearg = """

""" % argname

parser_definition = parser_body(parser_prototype,

libclinic.normalize_snippet(parsearg, indent=4))

elif has_option_groups:

# positional parameters with option groups

# (we have to generate lots of PyArg_ParseTuple calls

# in a big switch statement)

flags = "METH_VARARGS"

parser_prototype = self.PARSER_PROTOTYPE_VARARGS

parser_definition = parser_body(parser_prototype, ' {option_group_parsing}')

elif not requires_defining_class and pos_only == len(parameters) - pseudo_args:

if fastcall:

# positional-only, but no option groups

# we only need one call to _PyArg_ParseStack

flags = "METH_FASTCALL"

parser_prototype = self.PARSER_PROTOTYPE_FASTCALL

nargs = 'nargs'

argname_fmt = 'args[%d]'

else:

# positional-only, but no option groups

# we only need one call to PyArg_ParseTuple

flags = "METH_VARARGS"

parser_prototype = self.PARSER_PROTOTYPE_VARARGS

if limited_capi:

nargs = 'PyTuple_Size(args)'

argname_fmt = 'PyTuple_GetItem(args, %d)'

else:

nargs = 'PyTuple_GET_SIZE(args)'

argname_fmt = 'PyTuple_GET_ITEM(args, %d)'

left_args = f"{nargs} - {max_pos}"

max_args = self.NO_VARARG if (vararg != self.NO_VARARG) else max_pos

if limited_capi:

parser_code = []

if nargs != 'nargs':

nargs_def = f'Py_ssize_t nargs = {nargs};'

parser_code.append(libclinic.normalize_snippet(nargs_def, indent=4))

nargs = 'nargs'

if min_pos == max_args:

pl = '' if min_pos == 1 else 's'

parser_code.append(libclinic.normalize_snippet(f"""

""",

indent=4))

else:

if min_pos:

pl = '' if min_pos == 1 else 's'

parser_code.append(libclinic.normalize_snippet(f"""

""",

indent=4))

if max_args != self.NO_VARARG:

pl = '' if max_args == 1 else 's'