gh-87613: Argument Cliic @vectorcall decorator

Add `@vectorcall` as a decorator to Argument Clinic (AC) which generates a new
[Vectorcall Protocol](https://docs.python.org/3/c-api/call.html#the-vectorcall-protocol)
argument parsing C function named `{}_vectorcall`. This is only supported for
`__new__` and `__init__` currently to simplify implementation.

The generated code has similar or better performance to existing hand-written
cases for `list`, `float`, `str`, `tuple`, `enumerate`, `reversed`, and `int`.
Using the decorator added vectorcall to `bytearray` and construction got
1.09x faster. For more details see the comments in gh-87613.

The `@vectorcall` decorator has two options:
 - **zero_arg={C_FUNC}**: Some types, like `int`, can be called with zero
   arguments and return an immortal object in that case. Adding a shortcut is
   needed to match existing hand-written performance; provides an over 10%
   performance change for those cases.
  - **exact_only**: If the type is not an exact match delegate to the existing
  non-vectorcall implementation. NEeded for `str` to get matching performance
  while ensuring correct behavior.

Implementation details:
 - Adds support for the new decorator with arguments in the AC DSL Parser
 - Move keyword argument parsing generation from inline to a function so both
   vectorcall, `vc_`, and existing can share code generation.
 - Adds an `emit` helper to simplify code a bit from existing AC cases

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cmaloney

Lib/test/test_clinic.py

@@ -626,6 +626,7 @@ def test_directive_output_invalid_command(self):
              - 'impl_prototype'
              - 'parser_prototype'
              - 'parser_definition'
+             - 'vectorcall_definition'
              - 'cpp_endif'
              - 'methoddef_ifndef'
              - 'impl_definition'
@@ -2496,6 +2497,162 @@ def test_duplicate_coexist(self):
         """
         self.expect_failure(block, err, lineno=2)
 
+    def test_duplicate_vectorcall(self):
+        err = "Called @vectorcall twice"
+        block = """
+            module m
+            class Foo "FooObject *" ""
+            @vectorcall
+            @vectorcall
+            Foo.__init__
+        """
+        self.expect_failure(block, err, lineno=3)
+
+    def test_vectorcall_on_regular_method(self):
+        err = "@vectorcall can only be used with __init__ and __new__ methods"
+        block = """
+            module m
+            class Foo "FooObject *" ""
+            @vectorcall
+            Foo.some_method
+        """
+        self.expect_failure(block, err, lineno=3)
+
+    def test_vectorcall_on_module_function(self):
+        err = "@vectorcall can only be used with __init__ and __new__ methods"
+        block = """
+            module m
+            @vectorcall
+            m.fn
+        """
+        self.expect_failure(block, err, lineno=2)
+
+    def test_vectorcall_on_init(self):
+        block = """
+            module m
+            class Foo "FooObject *" "Foo_Type"
+            @vectorcall
+            Foo.__init__
+                iterable: object = NULL
+                /
+        """
+        func = self.parse_function(block, signatures_in_block=3,
+                                   function_index=2)
+        self.assertTrue(func.vectorcall)
+        self.assertFalse(func.vectorcall_exact_only)
+
+    def test_vectorcall_on_new(self):
+        block = """
+            module m
+            class Foo "FooObject *" "Foo_Type"
+            @classmethod
+            @vectorcall
+            Foo.__new__
+                x: object = NULL
+                /
+        """
+        func = self.parse_function(block, signatures_in_block=3,
+                                   function_index=2)
+        self.assertTrue(func.vectorcall)
+        self.assertFalse(func.vectorcall_exact_only)
+
+    def test_vectorcall_exact_only(self):
+        block = """
+            module m
+            class Foo "FooObject *" "Foo_Type"
+            @vectorcall exact_only
+            Foo.__init__
+                iterable: object = NULL
+                /
+        """
+        func = self.parse_function(block, signatures_in_block=3,
+                                   function_index=2)
+        self.assertTrue(func.vectorcall)
+        self.assertTrue(func.vectorcall_exact_only)
+
+    def test_vectorcall_init_with_kwargs(self):
+        block = """
+            module m
+            class Foo "FooObject *" "Foo_Type"
+            @vectorcall
+            Foo.__init__
+                source: object = NULL
+                encoding: str = NULL
+                errors: str = NULL
+        """
+        func = self.parse_function(block, signatures_in_block=3,
+                                   function_index=2)
+        self.assertTrue(func.vectorcall)
+
+    def test_vectorcall_new_with_kwargs(self):
+        block = """
+            module m
+            class Foo "FooObject *" "Foo_Type"
+            @classmethod
+            @vectorcall
+            Foo.__new__
+                source: object = NULL
+                *
+                encoding: str = NULL
+                errors: str = NULL
+        """
+        func = self.parse_function(block, signatures_in_block=3,
+                                   function_index=2)
+        self.assertTrue(func.vectorcall)
+
+    def test_vectorcall_init_no_args(self):
+        block = """
+            module m
+            class Foo "FooObject *" "Foo_Type"
+            @vectorcall
+            Foo.__init__
+        """
+        func = self.parse_function(block, signatures_in_block=3,
+                                   function_index=2)
+        self.assertTrue(func.vectorcall)
+
+    def test_vectorcall_zero_arg(self):
+        block = """
+            module m
+            class Foo "FooObject *" "Foo_Type"
+            @classmethod
+            @vectorcall zero_arg=_PyFoo_GetEmpty()
+            Foo.__new__
+                x: object = NULL
+                /
+        """
+        func = self.parse_function(block, signatures_in_block=3,
+                                   function_index=2)
+        self.assertTrue(func.vectorcall)
+        self.assertFalse(func.vectorcall_exact_only)
+        self.assertEqual(func.vectorcall_zero_arg, '_PyFoo_GetEmpty()')
+
+    def test_vectorcall_zero_arg_with_exact(self):
+        block = """
+            module m
+            class Foo "FooObject *" "Foo_Type"
+            @classmethod
+            @vectorcall exact_only zero_arg=get_cached()
+            Foo.__new__
+                x: object = NULL
+                /
+        """
+        func = self.parse_function(block, signatures_in_block=3,
+                                   function_index=2)
+        self.assertTrue(func.vectorcall)
+        self.assertTrue(func.vectorcall_exact_only)
+        self.assertEqual(func.vectorcall_zero_arg, 'get_cached()')
+
+    def test_vectorcall_invalid_kwarg(self):
+        err = "unknown argument"
+        block = """
+            module m
+            class Foo "FooObject *" ""
+            @vectorcall bogus=True
+            Foo.__init__
+        """
+        self.expect_failure(block, err, lineno=2)
+
     def test_unused_param(self):
         block = self.parse("""
             module foo

Tools/clinic/libclinic/app.py

@@ -121,6 +121,7 @@ def __init__(
             'impl_prototype': d('file'),
             'parser_prototype': d('suppress'),
             'parser_definition': d('file'),
+            'vectorcall_definition': d('file'),
             'cpp_endif': d('file'),
             'methoddef_ifndef': d('file', 1),
             'impl_definition': d('block'),

Tools/clinic/libclinic/clanguage.py

@@ -14,7 +14,7 @@
 from libclinic.function import (
     Module, Class, Function, Parameter,
     permute_optional_groups,
-    GETTER, SETTER, METHOD_INIT)
+    GETTER, SETTER, METHOD_INIT, METHOD_NEW)
 from libclinic.converters import self_converter
 from libclinic.parse_args import ParseArgsCodeGen
 if TYPE_CHECKING:
@@ -478,6 +478,24 @@ def render_function(
         template_dict['parser_parameters'] = ", ".join(data.impl_parameters[1:])
         template_dict['impl_arguments'] = ", ".join(data.impl_arguments)
 
+        # Vectorcall impl arguments: replace self/type with the appropriate
+        # expression for the vectorcall calling convention.
+        if f.vectorcall and f.cls:
+            if f.kind is METHOD_INIT:
+                # For __init__: self is a locally-allocated PyObject*
+                vc_first = f"({f.cls.typedef})self"
+            elif f.kind is METHOD_NEW:
+                # For __new__: type is PyObject* in vectorcall, need cast
+                vc_first = "_PyType_CAST(type)"
+            else:
+                raise AssertionError(
+                    f"Unhandled function kind for vectorcall: {f.kind!r}"
+                )
+            vc_impl_args = [vc_first] + data.impl_arguments[1:]
+            template_dict['vc_impl_arguments'] = ", ".join(vc_impl_args)
+        else:
+            template_dict['vc_impl_arguments'] = ""
+
         template_dict['return_conversion'] = libclinic.format_escape("".join(data.return_conversion).rstrip())
         template_dict['post_parsing'] = libclinic.format_escape("".join(data.post_parsing).rstrip())
         template_dict['cleanup'] = libclinic.format_escape("".join(data.cleanup))

Tools/clinic/libclinic/dsl_parser.py

@@ -302,6 +302,9 @@ def reset(self) -> None:
         self.critical_section = False
         self.target_critical_section = []
         self.disable_fastcall = False
+        self.vectorcall = False
+        self.vectorcall_exact_only = False
+        self.vectorcall_zero_arg = ''
         self.permit_long_summary = False
         self.permit_long_docstring_body = False
 
@@ -466,6 +469,24 @@ def at_staticmethod(self) -> None:
             fail("Can't set @staticmethod, function is not a normal callable")
         self.kind = STATIC_METHOD
 
+    def at_vectorcall(self, *args: str) -> None:
+        if self.vectorcall:
+            fail("Called @vectorcall twice!")
+        self.vectorcall = True
+        for arg in args:
+            if '=' in arg:
+                key, value = arg.split('=', 1)
+            else:
+                key, value = arg, ''
+            if key == 'exact_only':
+                self.vectorcall_exact_only = True
+            elif key == 'zero_arg':
+                if not value:
+                    fail("@vectorcall zero_arg requires a value")
+                self.vectorcall_zero_arg = value
+            else:
+                fail(f"@vectorcall: unknown argument {key!r}")
+
     def at_coexist(self) -> None:
         if self.coexist:
             fail("Called @coexist twice!")
@@ -599,6 +620,10 @@ def normalize_function_kind(self, fullname: str) -> None:
         elif name == '__init__':
             self.kind = METHOD_INIT
 
+        # Validate @vectorcall usage.
+        if self.vectorcall and not self.kind.new_or_init:
+            fail("@vectorcall can only be used with __init__ and __new__ methods currently")
+
     def resolve_return_converter(
         self, full_name: str, forced_converter: str
     ) -> CReturnConverter:
@@ -723,7 +748,10 @@ def state_modulename_name(self, line: str) -> None:
             critical_section=self.critical_section,
             disable_fastcall=self.disable_fastcall,
             target_critical_section=self.target_critical_section,
-            forced_text_signature=self.forced_text_signature
+            forced_text_signature=self.forced_text_signature,
+            vectorcall=self.vectorcall,
+            vectorcall_exact_only=self.vectorcall_exact_only,
+            vectorcall_zero_arg=self.vectorcall_zero_arg,
         )
         self.add_function(func)
 

Tools/clinic/libclinic/function.py

@@ -111,6 +111,9 @@ class Function:
     critical_section: bool = False
     disable_fastcall: bool = False
     target_critical_section: list[str] = dc.field(default_factory=list)
+    vectorcall: bool = False
+    vectorcall_exact_only: bool = False
+    vectorcall_zero_arg: str = ''
 
     def __post_init__(self) -> None:
         self.parent = self.cls or self.module