Add / and * parameter handling (#340)

Add / and * parameter handling to functions.

Author: mauriciogardini

.chronus/changes/feature-python-asterisk-2025-10-21-22-35-35.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@alloy-js/python"
+---
+
+Add / and * parameter handling

packages/python/src/components/CallSignature.tsx

@@ -14,8 +14,16 @@ import { createPythonSymbol } from "../symbol-creation.js";
 import { PythonOutputSymbol } from "../symbols/index.js";
 import { Atom } from "./Atom.jsx";
 
+export type ParameterMarker = "*" | "/";
+
+function isParameterMarker(
+  param: string | ParameterDescriptor | undefined,
+): param is ParameterMarker {
+  return typeof param === "string" && (param === "*" || param === "/");
+}
+
 export interface CallSignatureParametersProps {
-  readonly parameters?: (ParameterDescriptor | string)[];
+  readonly parameters?: (ParameterDescriptor | ParameterMarker | string)[];
   readonly args?: boolean;
   readonly kwargs?: boolean;
 }
@@ -34,13 +42,11 @@ export interface CallSignatureParametersProps {
  * ```
  */
 export function CallSignatureParameters(props: CallSignatureParametersProps) {
-  const parameters = normalizeAndDeclareParameters(props.parameters ?? []);
-
   const parameterList = computed(() => {
-    const params = [];
-    // Add regular parameters
-    parameters.forEach((param) => {
-      params.push(parameter(param));
+    const params = (props.parameters ?? []).map((p) => {
+      return isParameterMarker(p) ? p : (
+          parameter(normalizeAndDeclareParameter(p))
+        );
     });
 
     // Add *args if specified
@@ -88,40 +94,39 @@ interface DeclaredParameterDescriptor
   TypeSlot?: SymbolSlot;
 }
 
-function normalizeAndDeclareParameters(
-  parameters: (ParameterDescriptor | string)[],
-): DeclaredParameterDescriptor[] {
-  return parameters.map((param) => {
-    if (isParameterDescriptor(param)) {
-      const TypeSlot = createSymbolSlot();
-
-      const symbol = createPythonSymbol(
-        param.name,
-        {
-          refkeys: param.refkey,
-          type: TypeSlot.firstSymbol,
-        },
-        "parameter",
-      );
-
-      return {
-        ...param,
-        symbol,
-        TypeSlot,
-      };
-    } else {
-      const symbol = createPythonSymbol(param, {}, "parameter");
-      return { refkeys: symbol.refkeys, symbol };
-    }
-  });
+function normalizeAndDeclareParameter(
+  param: ParameterDescriptor | string,
+): DeclaredParameterDescriptor {
+  if (isParameterDescriptor(param)) {
+    const TypeSlot = createSymbolSlot();
+
+    const symbol = createPythonSymbol(
+      param.name,
+      {
+        refkeys: param.refkey,
+        type: TypeSlot.firstSymbol,
+      },
+      "parameter",
+    );
+
+    return {
+      ...param,
+      symbol,
+      TypeSlot,
+    };
+  } else {
+    const symbol = createPythonSymbol(param, {}, "parameter");
+    return { symbol };
+  }
 }
 
 export interface CallSignatureProps {
   /**
-   * The parameters to the call signature. Can be an array of strings (for parameters
-   * which don't have a type or a default value) or {@link ParameterDescriptor}s.
+   * The parameters to the call signature. Can be an array of strings (for simple
+   * parameter names), {@link ParameterDescriptor}s, or special markers ("*" for
+   * keyword-only, "/" for positional-only).
    */
-  parameters?: (ParameterDescriptor | string)[];
+  parameters?: (ParameterDescriptor | ParameterMarker | string)[];
 
   /**
    * The type parameters of the call signature, e.g. for a generic function.

packages/python/test/callsignatures.test.tsx

@@ -96,6 +96,35 @@ describe("Call Signature Parameters", () => {
       a: int = 5, b: str = "hello"
     `);
   });
+  it("renders keyword-only parameters with * marker", () => {
+    const result = toSourceText([
+      <py.CallSignatureParameters
+        parameters={[
+          { name: "a", type: "str" },
+          "*",
+          { name: "b", type: "int", default: 10 },
+          { name: "c", type: "bool", default: true },
+        ]}
+      />,
+    ]);
+    expect(result).toRenderTo(d`
+      a: str, *, b: int = 10, c: bool = True
+    `);
+  });
+  it("renders only keyword-only parameters with * marker at start", () => {
+    const result = toSourceText([
+      <py.CallSignatureParameters
+        parameters={[
+          "*",
+          { name: "a", type: "str", default: "hello" },
+          { name: "b", type: "int", default: 42 },
+        ]}
+      />,
+    ]);
+    expect(result).toRenderTo(d`
+      *, a: str = "hello", b: int = 42
+    `);
+  });
 });
 
 describe("Call Signature", () => {
@@ -281,4 +310,85 @@ describe("Call Signature - Parameter Descriptors", () => {
       [T, U](a: int, b: str = "default_value") -> int
     `);
   });
+  it("renders a call signature with keyword-only parameters using * marker", () => {
+    const result = toSourceText([
+      <py.CallSignature
+        parameters={[
+          { name: "id", type: "str" },
+          "*",
+          { name: "locale", type: "str", default: "en-US" },
+          { name: "debug", type: "bool", default: false },
+        ]}
+        returnType="str"
+      />,
+    ]);
+    expect(result).toRenderTo(d`
+      (id: str, *, locale: str = "en-US", debug: bool = False) -> str
+    `);
+  });
+  it("renders a call signature with only keyword-only parameters", () => {
+    const result = toSourceText([
+      <py.CallSignature
+        parameters={[
+          "*",
+          { name: "name", type: "str", default: "alice" },
+          { name: "age", type: "int", default: 30 },
+        ]}
+        returnType="None"
+      />,
+    ]);
+    expect(result).toRenderTo(d`
+      (*, name: str = "alice", age: int = 30) -> None
+    `);
+  });
+  it("renders a call signature with positional, keyword-only, and *args/**kwargs", () => {
+    const result = toSourceText([
+      <py.CallSignature
+        parameters={[
+          { name: "a", type: "int" },
+          "*",
+          { name: "b", type: "str", default: "hello" },
+        ]}
+        args
+        kwargs
+        returnType="None"
+      />,
+    ]);
+    expect(result).toRenderTo(d`
+      (a: int, *, b: str = "hello", *args, **kwargs) -> None
+    `);
+  });
+  it("renders a call signature with positional-only parameters using / marker", () => {
+    const result = toSourceText([
+      <py.CallSignature
+        parameters={[
+          { name: "a", type: "int" },
+          { name: "b", type: "str" },
+          "/",
+          { name: "c", type: "bool" },
+        ]}
+        returnType="None"
+      />,
+    ]);
+    expect(result).toRenderTo(d`
+      (a: int, b: str, /, c: bool) -> None
+    `);
+  });
+  it("renders a call signature with positional-only, regular, and keyword-only parameters", () => {
+    const result = toSourceText([
+      <py.CallSignature
+        parameters={[
+          { name: "a", type: "int" },
+          "/",
+          { name: "b", type: "str" },
+          "*",
+          { name: "c", type: "bool", default: true },
+        ]}
+        returnType="None"
+      />,
+    ]);
+    expect(result).toRenderTo(d`
+      (a: int, /, b: str, *, c: bool = True) -> None
+    `);
+  });
 });