@alloy-js/python 0.3.0-dev.3 → 0.3.0-dev.5

package/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.

package/src/components/EnumMember.tsx

@@ -3,7 +3,7 @@ import { enumModule } from "../builtins/python.js";
 import { createPythonSymbol } from "../symbol-creation.js";
 import { PythonOutputSymbol } from "../symbols/index.js";
 import { Atom } from "./Atom.jsx";
-import { SimpleInlineMemberComment } from "./PyDoc.jsx";
+import { InlineDoc } from "./PyDoc.jsx";
 
 export interface EnumMemberProps {
   /**
@@ -73,7 +73,7 @@ export function EnumMember(props: EnumMemberProps) {
       <>
         '{sym.name}'<Show when={valueCode !== undefined}> : {valueCode}</Show>
         <Show when={props.doc !== undefined}>
-          <SimpleInlineMemberComment>{props.doc}</SimpleInlineMemberComment>
+          <InlineDoc>{props.doc}</InlineDoc>
         </Show>
       </>
     );
@@ -83,7 +83,7 @@ export function EnumMember(props: EnumMemberProps) {
       {sym.name}
       <Show when={valueCode !== undefined}> = {valueCode}</Show>
       <Show when={props.doc !== undefined}>
-        <SimpleInlineMemberComment>{props.doc}</SimpleInlineMemberComment>
+        <InlineDoc>{props.doc}</InlineDoc>
       </Show>
     </>
   );

package/src/components/PyDoc.tsx

@@ -259,6 +259,28 @@ export function PyDoc(props: PyDocProps) {
   );
 }
 
+export interface InlineDocProps {
+  children: Children;
+}
+
+/**
+ * An inline documentation component for attribute docstrings.
+ * Unlike PyDoc, this doesn't add a trailing line break after the closing quotes,
+ * which is appropriate for documenting consecutive attributes like enum members.
+ */
+export function InlineDoc(props: InlineDocProps) {
+  return (
+    <>
+      <hardline />
+      {'"""'}
+      <hbr />
+      {props.children}
+      <hbr />
+      {'"""'}
+    </>
+  );
+}
+
 export interface PyDocExampleProps {
   children: Children;
 }
@@ -373,14 +395,6 @@ export interface SimpleInlineCommentProps {
   children: Children;
 }
 
-export function SimpleInlineMemberComment(props: SimpleInlineCommentProps) {
-  return (
-    <>
-      {"  "}#: <Prose>{props.children}</Prose>
-    </>
-  );
-}
-
 interface GoogleStyleFunctionDocProps extends Omit<FunctionDocProps, "style"> {}
 
 /**

package/temp/api.json

@@ -831,6 +831,15 @@
                   "text": "ParameterDescriptor",
                   "canonicalReference": "@alloy-js/python!ParameterDescriptor:interface"
                 },
+                {
+                  "kind": "Content",
+                  "text": " | "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ParameterMarker",
+                  "canonicalReference": "@alloy-js/python!ParameterMarker:type"
+                },
                 {
                   "kind": "Content",
                   "text": " | string)[]"
@@ -846,7 +855,7 @@
               "name": "parameters",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 4
+                "endIndex": 6
               }
             }
           ],
@@ -924,7 +933,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/python!CallSignatureProps#parameters:member",
-              "docComment": "/**\n * The parameters to the call signature. Can be an array of strings (for parameters\n * which don't have a type or a default value) or {@link ParameterDescriptor}s.\n */\n",
+              "docComment": "/**\n * The parameters to the call signature. Can be an array of strings (for simple\n * parameter names), {@link ParameterDescriptor}s, or special markers (\"*\" for\n * keyword-only, \"/\" for positional-only).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -939,6 +948,15 @@
                   "text": "ParameterDescriptor",
                   "canonicalReference": "@alloy-js/python!ParameterDescriptor:interface"
                 },
+                {
+                  "kind": "Content",
+                  "text": " | "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ParameterMarker",
+                  "canonicalReference": "@alloy-js/python!ParameterMarker:type"
+                },
                 {
                   "kind": "Content",
                   "text": " | string)[]"
@@ -954,7 +972,7 @@
               "name": "parameters",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 4
+                "endIndex": 6
               }
             },
             {
@@ -5431,6 +5449,99 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@alloy-js/python!InlineDoc:function(1)",
+          "docComment": "/**\n * An inline documentation component for attribute docstrings.\n * Unlike PyDoc, this doesn't add a trailing line break after the closing quotes,\n * which is appropriate for documenting consecutive attributes like enum members.\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function InlineDoc(props: "
+            },
+            {
+              "kind": "Reference",
+              "text": "InlineDocProps",
+              "canonicalReference": "@alloy-js/python!InlineDocProps:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Reference",
+              "text": "Children",
+              "canonicalReference": "@alloy-js/core!Children:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/components/PyDoc.tsx",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "props",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "InlineDoc"
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@alloy-js/python!InlineDocProps:interface",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface InlineDocProps "
+            }
+          ],
+          "fileUrlPath": "src/components/PyDoc.tsx",
+          "releaseTag": "Public",
+          "name": "InlineDocProps",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/python!InlineDocProps#children:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "children: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Children",
+                  "canonicalReference": "@alloy-js/core!Children:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "children",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/python!isParameterDescriptor:function(1)",
@@ -7291,6 +7402,32 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@alloy-js/python!ParameterMarker:type",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type ParameterMarker = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"*\" | \"/\""
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/components/CallSignature.tsx",
+          "releaseTag": "Public",
+          "name": "ParameterMarker",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/python!PropertyDeclaration:function(1)",
@@ -9731,53 +9868,6 @@
           ],
           "extendsTokenRanges": []
         },
-        {
-          "kind": "Function",
-          "canonicalReference": "@alloy-js/python!SimpleInlineMemberComment:function(1)",
-          "docComment": "",
-          "excerptTokens": [
-            {
-              "kind": "Content",
-              "text": "export declare function SimpleInlineMemberComment(props: "
-            },
-            {
-              "kind": "Reference",
-              "text": "SimpleInlineCommentProps",
-              "canonicalReference": "@alloy-js/python!SimpleInlineCommentProps:interface"
-            },
-            {
-              "kind": "Content",
-              "text": "): "
-            },
-            {
-              "kind": "Reference",
-              "text": "Children",
-              "canonicalReference": "@alloy-js/core!Children:type"
-            },
-            {
-              "kind": "Content",
-              "text": ";"
-            }
-          ],
-          "fileUrlPath": "src/components/PyDoc.tsx",
-          "returnTypeTokenRange": {
-            "startIndex": 3,
-            "endIndex": 4
-          },
-          "releaseTag": "Public",
-          "overloadIndex": 1,
-          "parameters": [
-            {
-              "parameterName": "props",
-              "parameterTypeTokenRange": {
-                "startIndex": 1,
-                "endIndex": 2
-              },
-              "isOptional": false
-            }
-          ],
-          "name": "SimpleInlineMemberComment"
-        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/python!SourceFile:function(1)",

package/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
+    `);
+  });
 });

package/test/pydocs.test.tsx

@@ -195,40 +195,6 @@ describe("SimpleInlineComment", () => {
   });
 });
 
-describe("SimpleInlineMemberComment", () => {
-  it("renders inline member comment", () => {
-    const res = toSourceText([
-      <>
-        status: int
-        <py.SimpleInlineMemberComment>
-          HTTP status code
-        </py.SimpleInlineMemberComment>
-      </>,
-    ]);
-    expect(res).toRenderTo(
-      d`
-          status: int  #: HTTP status code
-          `,
-    );
-  });
-
-  it("renders inline member comment for variable declaration", () => {
-    const res = toSourceText([
-      <>
-        max_retries = 3
-        <py.SimpleInlineMemberComment>
-          Maximum number of retry attempts
-        </py.SimpleInlineMemberComment>
-      </>,
-    ]);
-    expect(res).toRenderTo(
-      d`
-          max_retries = 3  #: Maximum number of retry attempts
-          `,
-    );
-  });
-});
-
 describe("New Documentation Components", () => {
   it("ModuleDoc renders correctly", () => {
     const res = toSourceText([
@@ -1177,9 +1143,18 @@ describe("Full example", () => {
           An enum representing colors.
           """
 
-          RED = 1  #: The color red.
-          GREEN = 2  #: The color green.
-          BLUE = 3  #: The color blue.
+          RED = 1
+          """
+          The color red.
+          """
+          GREEN = 2
+          """
+          The color green.
+          """
+          BLUE = 3
+          """
+          The color blue.
+          """
 
 
     `;