@alloy-js/python 0.3.0-dev.0 → 0.3.0-dev.2

package/src/components/ClassDeclaration.tsx

@@ -1,4 +1,4 @@
-import { Children, List, Name, Show, childrenArray } from "@alloy-js/core";
+import { Children, List, Name, Show, createContentSlot } from "@alloy-js/core";
 import { createPythonSymbol } from "../symbol-creation.js";
 import { BaseDeclarationProps, Declaration } from "./Declaration.js";
 import { MemberScope } from "./MemberScope.jsx";
@@ -53,8 +53,7 @@ export function ClassDeclaration(props: ClassDeclarationProps) {
     "class",
   );
 
-  const hasChildren =
-    childrenArray(() => props.children).filter((c) => Boolean(c)).length > 0;
+  const ContentSlot = createContentSlot();
 
   return (
     <Declaration symbol={sym}>
@@ -66,7 +65,8 @@ export function ClassDeclaration(props: ClassDeclarationProps) {
             {props.doc}
             <line />
           </Show>
-          {hasChildren ? props.children : "pass"}
+          <ContentSlot.WhenEmpty>pass</ContentSlot.WhenEmpty>
+          <ContentSlot>{props.children}</ContentSlot>
         </PythonBlock>
       </MemberScope>
     </Declaration>

package/src/components/DataclassDeclaration.tsx

@@ -0,0 +1,185 @@
+import { For, Show } from "@alloy-js/core";
+import { snakeCase } from "change-case";
+import { dataclassesModule } from "../builtins/python.js";
+import { usePythonScope } from "../symbols/scopes.js";
+import { Atom } from "./Atom.jsx";
+import type { ClassDeclarationProps } from "./ClassDeclaration.js";
+import { ClassDeclaration } from "./ClassDeclaration.js";
+import { StatementList } from "./StatementList.js";
+
+/**
+ * Validate decorator-only rules that do not depend on class members.
+ */
+function validateDataclassDecoratorArgs(kwargs: DataclassDecoratorKwargs) {
+  if (kwargs.weakrefSlot === true && kwargs.slots !== true) {
+    throw new Error(
+      "weakref_slot=True requires slots=True in @dataclass decorator",
+    );
+  }
+  if (kwargs.order === true && kwargs.eq === false) {
+    throw new Error("order=True requires eq=True in @dataclass decorator");
+  }
+}
+
+/**
+ * Validate symbol-level conflicts. Must be called from within a member scope
+ * (inside the class body) so member symbols are available.
+ */
+function validateDataclassMemberConflicts(kwargs: DataclassDecoratorKwargs) {
+  const scope = usePythonScope();
+  const owner: any = (scope as any).ownerSymbol;
+  if (!owner) return;
+
+  const hasMemberNamed = (name: string): boolean => {
+    const instanceNames: Set<string> | undefined = (
+      owner.instanceMembers as any
+    )?.symbolNames;
+    const staticNames: Set<string> | undefined = (owner.staticMembers as any)
+      ?.symbolNames;
+    return Boolean(instanceNames?.has(name) || staticNames?.has(name));
+  };
+
+  if (kwargs.order === true) {
+    for (const m of ["__lt__", "__le__", "__gt__", "__ge__"]) {
+      if (hasMemberNamed(m)) {
+        throw new TypeError(
+          `Cannot specify order=True when the class already defines ${m}()`,
+        );
+      }
+    }
+  }
+
+  if (kwargs.unsafeHash === true && hasMemberNamed("__hash__")) {
+    throw new TypeError(
+      "Cannot specify unsafe_hash=True when the class already defines __hash__()",
+    );
+  }
+
+  if (kwargs.frozen === true) {
+    if (hasMemberNamed("__setattr__")) {
+      throw new TypeError(
+        "Cannot specify frozen=True when the class already defines __setattr__()",
+      );
+    }
+    if (hasMemberNamed("__delattr__")) {
+      throw new TypeError(
+        "Cannot specify frozen=True when the class already defines __delattr__()",
+      );
+    }
+  }
+
+  if (kwargs.slots === true && hasMemberNamed("__slots__")) {
+    throw new TypeError(
+      "Cannot specify slots=True when the class already defines __slots__()",
+    );
+  }
+
+  // Enforce at most one KW_ONLY sentinel as a symbol
+  let kwOnlyCount = 0;
+  for (const sym of owner.instanceMembers as Iterable<any>) {
+    if (sym.originalName === "_") kwOnlyCount++;
+  }
+  if (kwOnlyCount > 1) {
+    throw new Error("Only one KW_ONLY sentinel is allowed per dataclass body");
+  }
+}
+
+/**
+ * Allowed keyword arguments for the Python `@dataclass(...)` decorator.
+ * Single source of truth: runtime keys and compile-time type are derived here.
+ */
+export const dataclassDecoratorKeys = [
+  "init",
+  "repr",
+  "eq",
+  "order",
+  "unsafeHash",
+  "frozen",
+  "matchArgs",
+  "kwOnly",
+  "slots",
+  "weakrefSlot",
+] as const;
+export const dataclassDecoratorKeySet = new Set<string>(
+  dataclassDecoratorKeys as unknown as string[],
+);
+export type DataclassDecoratorKey = (typeof dataclassDecoratorKeys)[number];
+export type DataclassDecoratorKwargs = Partial<
+  Record<DataclassDecoratorKey, boolean>
+>;
+
+export interface DataclassDeclarationProps
+  extends ClassDeclarationProps,
+    DataclassDecoratorKwargs {}
+
+/**
+ * Renders a Python dataclass.
+ *
+ * Example:
+ * ```tsx
+ * <py.DataclassDeclaration name="User" kwOnly>
+ *   <py.VariableDeclaration instanceVariable omitNone name="id" type="int" />
+ *   <py.VariableDeclaration instanceVariable name={namekey("_", { ignoreNamePolicy: true })} type={dataclassesModule["."].KW_ONLY} omitNone />
+ *   <py.VariableDeclaration
+ *     instanceVariable
+ *     name="name"
+ *     type="str"
+ *     initializer={"Anonymous"}
+ *   />
+ * </py.DataclassDeclaration>
+ * ```
+ * Will render as:
+ * ```py
+ * from dataclasses import dataclass
+ * from dataclasses import KW_ONLY
+ *
+ * @dataclass(kw_only=True)
+ * class User:
+ *     id: int
+ *     _: KW_ONLY
+ *     name: str = "Anonymous"
+ * ```
+ */
+export function DataclassDeclaration(props: DataclassDeclarationProps) {
+  // Collect flags from props in the order they appear (preserves emission order)
+  const decoratorEntries: Array<[string, any]> = [];
+  const kwargs = {} as DataclassDecoratorKwargs;
+  for (const key of Object.keys(props)) {
+    // Only include known flags; skip undefined values
+    if (dataclassDecoratorKeySet.has(key)) {
+      const value = (props as any)[key];
+      if (value !== undefined) {
+        (kwargs as any)[key] = value;
+        decoratorEntries.push([snakeCase(key), value]);
+      }
+    }
+  }
+  const hasDecoratorArgs = decoratorEntries.length > 0;
+
+  if (hasDecoratorArgs) {
+    validateDataclassDecoratorArgs(kwargs);
+  }
+
+  return (
+    <>
+      {"@"}
+      {dataclassesModule["."].dataclass}
+      <Show when={hasDecoratorArgs}>
+        (
+        <For each={decoratorEntries} comma space>
+          {([k, v]) => (
+            <>
+              {k}=<Atom jsValue={v} />
+            </>
+          )}
+        </For>
+        )
+      </Show>
+      <hbr />
+      <ClassDeclaration name={props.name} bases={props.bases} doc={props.doc}>
+        <StatementList>{props.children}</StatementList>
+        {validateDataclassMemberConflicts(kwargs as DataclassDecoratorKwargs)}
+      </ClassDeclaration>
+    </>
+  );
+}

package/src/components/FunctionBase.tsx

@@ -1,4 +1,4 @@
-import { Name, Show } from "@alloy-js/core";
+import { createContentSlot, Name, Show } from "@alloy-js/core";
 import { PythonOutputSymbol } from "../index.js";
 import { getCallSignatureProps } from "../utils.js";
 import { CallSignature, CallSignatureProps } from "./CallSignature.jsx";
@@ -67,7 +67,7 @@ export function BaseFunctionDeclaration(props: BaseFunctionDeclarationProps) {
       parameters = props.parameters;
   }
   const sym: PythonOutputSymbol = props.sym;
-
+  const ContentSlot = createContentSlot();
   return (
     <>
       <Declaration {...props} nameKind="function" symbol={sym}>
@@ -79,7 +79,8 @@ export function BaseFunctionDeclaration(props: BaseFunctionDeclarationProps) {
           />
           <PythonBlock opener=":">
             <Show when={Boolean(props.doc)}>{props.doc}</Show>
-            {props.children ?? "pass"}
+            <ContentSlot.WhenEmpty>pass</ContentSlot.WhenEmpty>
+            <ContentSlot>{props.children}</ContentSlot>
           </PythonBlock>
         </LexicalScope>
       </Declaration>

package/src/components/PyDoc.tsx

@@ -1,5 +1,14 @@
-import { For, Indent, List, Prose, Show, childrenArray } from "@alloy-js/core";
-import { Children } from "@alloy-js/core/jsx-runtime";
+import {
+  Children,
+  For,
+  Indent,
+  List,
+  Prose,
+  Show,
+  childrenArray,
+  computed,
+  isKeyedChild,
+} from "@alloy-js/core";
 import { ParameterDescriptor } from "../parameter-descriptor.js";
 import { Atom } from "./Atom.jsx";
 
@@ -258,26 +267,50 @@ export interface PyDocExampleProps {
  * Create a PyDoc example, which is prepended by \>\>.
  */
 export function PyDocExample(props: PyDocExampleProps) {
-  const children = childrenArray(() => props.children);
-  let lines: string[] = [];
+  const lines = computed(() => {
+    const kids = childrenArray(() => props.children, {
+      preserveFragments: true,
+    });
+    const out: Children[] = [];
+
+    const isBr = (node: any): boolean => {
+      if (node == null) return false;
+      const keyed = isKeyedChild(node as any);
+      const tag = keyed ? (node as any).tag : (node as any)?.tag;
+      const kind = (node as any)?.kind;
+      // Consider only <br /> as a line splitter (not rendered as content).
+      return tag === "br" || kind === "br";
+    };
+
+    // Handles a single string child: split on newlines to produce lines.
+    const splitAndTrim = (s: string): string[] =>
+      s
+        .split(/\r?\n/)
+        .map((x) => x.trim())
+        .filter((x) => x.length > 0);
+
+    if (kids.length === 1 && typeof kids[0] === "string") {
+      return splitAndTrim(kids[0] as string);
+    }
 
-  if (children.length === 1 && typeof children[0] === "string") {
-    // Split, trim each line, and filter out empty lines
-    lines = children[0]
-      .split(/\r?\n/)
-      .map((line) => line.trim())
-      .filter((line) => line.length > 0);
-  } else {
-    // For non-string children, filter out empty/whitespace-only strings
-    lines = children
-      .map((child) => (typeof child === "string" ? child : ""))
-      .map((line) => line.trim())
-      .filter((line) => line.length > 0);
-  }
+    // Handles mixed children: each child becomes a line, string children
+    // may include embedded newlines, and <br /> acts as a line split.
+    for (const child of kids) {
+      if (child == null || isBr(child)) continue;
+      if (typeof child === "string") {
+        // String children: split on newlines to produce lines.
+        for (const seg of splitAndTrim(child)) out.push(seg);
+      } else {
+        // Non-string child (component/fragment) are preserved as their own doctest line.
+        out.push(child);
+      }
+    }
+    return out;
+  });
 
   return (
     <>
-      <For each={lines}>
+      <For each={lines.value}>
         {(line) => (
           <>
             {">> "}
@@ -294,12 +327,32 @@ export interface SimpleCommentBlockProps {
 }
 
 export function SimpleCommentBlock(props: SimpleCommentBlockProps) {
+  const children = childrenArray(() => props.children);
+  let content: Children;
+  if (children.length === 1 && typeof children[0] === "string") {
+    const raw = children[0] as string;
+    if (raw.includes("\n") || raw.includes("\\n")) {
+      const parts = raw.split(/\r?\n|\\n/);
+      content = (
+        <>
+          {parts.map((p, i) => (
+            <>
+              <Prose>{p}</Prose>
+              {i < parts.length - 1 && <hbr />}
+            </>
+          ))}
+        </>
+      );
+    } else {
+      content = <Prose>{props.children}</Prose>;
+    }
+  } else {
+    content = <Prose>{props.children}</Prose>;
+  }
+
   return (
     <>
-      #{" "}
-      <align string="# ">
-        <Prose>{props.children}</Prose>
-      </align>
+      # <align string="# ">{content}</align>
     </>
   );
 }

package/src/components/UnionTypeExpression.tsx

@@ -1,26 +1,23 @@
-import { Children, For, childrenArray } from "@alloy-js/core";
+import { Children, List } from "@alloy-js/core";
 
 export interface UnionTypeExpressionProps {
   children: Children;
 }
 
 export function UnionTypeExpression(props: UnionTypeExpressionProps) {
-  const items = childrenArray(() => props.children);
   return (
     <group>
       <ifBreak>(</ifBreak>
       <indent>
         <sbr />
-        <For
-          each={items}
+        <List
+          children={props.children}
           joiner={
             <>
               <br />|{" "}
             </>
           }
-        >
-          {(child) => child}
-        </For>
+        />
       </indent>
       <sbr />
       <ifBreak>)</ifBreak>

package/src/components/index.ts

@@ -4,6 +4,7 @@ export * from "./ClassDeclaration.js";
 export * from "./ClassInstantiation.js";
 export * from "./ClassMethodDeclaration.js";
 export * from "./ConstructorDeclaration.js";
+export * from "./DataclassDeclaration.js";
 export * from "./Declaration.js";
 export * from "./DunderMethodDeclaration.js";
 export * from "./EnumDeclaration.js";

package/temp/api.json

@@ -2358,6 +2358,273 @@
             }
           ]
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@alloy-js/python!DataclassDeclaration:function(1)",
+          "docComment": "/**\n * Renders a Python dataclass.\n *\n * Example:\n * ```tsx\n * <py.DataclassDeclaration name=\"User\" kwOnly>\n *   <py.VariableDeclaration instanceVariable omitNone name=\"id\" type=\"int\" />\n *   <py.VariableDeclaration instanceVariable name={namekey(\"_\", { ignoreNamePolicy: true })} type={dataclassesModule[\".\"].KW_ONLY} omitNone />\n *   <py.VariableDeclaration\n *     instanceVariable\n *     name=\"name\"\n *     type=\"str\"\n *     initializer={\"Anonymous\"}\n *   />\n * </py.DataclassDeclaration>\n * ```\n *\n * Will render as:\n * ```py\n * from dataclasses import dataclass\n * from dataclasses import KW_ONLY\n *\n * @dataclass(kw_only=True)\n * class User:\n *     id: int\n *     _: KW_ONLY\n *     name: str = \"Anonymous\"\n * ```\n *\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function DataclassDeclaration(props: "
+            },
+            {
+              "kind": "Reference",
+              "text": "DataclassDeclarationProps",
+              "canonicalReference": "@alloy-js/python!DataclassDeclarationProps:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "import(\"@alloy-js/core\")."
+            },
+            {
+              "kind": "Reference",
+              "text": "Children",
+              "canonicalReference": "@alloy-js/core!Children:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/components/DataclassDeclaration.tsx",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 5
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "props",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "DataclassDeclaration"
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@alloy-js/python!DataclassDeclarationProps:interface",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface DataclassDeclarationProps extends "
+            },
+            {
+              "kind": "Reference",
+              "text": "ClassDeclarationProps",
+              "canonicalReference": "@alloy-js/python!ClassDeclarationProps:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ", "
+            },
+            {
+              "kind": "Reference",
+              "text": "DataclassDecoratorKwargs",
+              "canonicalReference": "@alloy-js/python!DataclassDecoratorKwargs:type"
+            },
+            {
+              "kind": "Content",
+              "text": " "
+            }
+          ],
+          "fileUrlPath": "src/components/DataclassDeclaration.tsx",
+          "releaseTag": "Public",
+          "name": "DataclassDeclarationProps",
+          "preserveMemberOrder": false,
+          "members": [],
+          "extendsTokenRanges": [
+            {
+              "startIndex": 1,
+              "endIndex": 2
+            },
+            {
+              "startIndex": 3,
+              "endIndex": 4
+            }
+          ]
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@alloy-js/python!DataclassDecoratorKey:type",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type DataclassDecoratorKey = "
+            },
+            {
+              "kind": "Content",
+              "text": "(typeof "
+            },
+            {
+              "kind": "Reference",
+              "text": "dataclassDecoratorKeys",
+              "canonicalReference": "@alloy-js/python!dataclassDecoratorKeys:var"
+            },
+            {
+              "kind": "Content",
+              "text": ")[number]"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/components/DataclassDeclaration.tsx",
+          "releaseTag": "Public",
+          "name": "DataclassDecoratorKey",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 4
+          }
+        },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@alloy-js/python!dataclassDecoratorKeys:var",
+          "docComment": "/**\n * Allowed keyword arguments for the Python `@dataclass(...)` decorator.\n * Single source of truth: runtime keys and compile-time type are derived here.\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "dataclassDecoratorKeys: "
+            },
+            {
+              "kind": "Content",
+              "text": "readonly [\"init\", \"repr\", \"eq\", \"order\", \"unsafeHash\", \"frozen\", \"matchArgs\", \"kwOnly\", \"slots\", \"weakrefSlot\"]"
+            }
+          ],
+          "fileUrlPath": "src/components/DataclassDeclaration.tsx",
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "dataclassDecoratorKeys",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@alloy-js/python!dataclassDecoratorKeySet:var",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "dataclassDecoratorKeySet: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Set",
+              "canonicalReference": "!Set:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<string>"
+            }
+          ],
+          "fileUrlPath": "src/components/DataclassDeclaration.tsx",
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "dataclassDecoratorKeySet",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 3
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@alloy-js/python!DataclassDecoratorKwargs:type",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type DataclassDecoratorKwargs = "
+            },
+            {
+              "kind": "Reference",
+              "text": "Partial",
+              "canonicalReference": "!Partial:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "Record",
+              "canonicalReference": "!Record:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "DataclassDecoratorKey",
+              "canonicalReference": "@alloy-js/python!DataclassDecoratorKey:type"
+            },
+            {
+              "kind": "Content",
+              "text": ", boolean>>"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/components/DataclassDeclaration.tsx",
+          "releaseTag": "Public",
+          "name": "DataclassDecoratorKwargs",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 7
+          }
+        },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@alloy-js/python!dataclassesModule:var",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "dataclassesModule: "
+            },
+            {
+              "kind": "Content",
+              "text": "import(\"../create-module.js\")."
+            },
+            {
+              "kind": "Reference",
+              "text": "ModuleRefkeys",
+              "canonicalReference": "@alloy-js/python!ModuleRefkeys:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<{\n    readonly \".\": [\"dataclass\", \"KW_ONLY\"];\n}> & "
+            },
+            {
+              "kind": "Reference",
+              "text": "SymbolCreator",
+              "canonicalReference": "@alloy-js/core!SymbolCreator:interface"
+            }
+          ],
+          "fileUrlPath": "src/builtins/python.ts",
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "dataclassesModule",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 5
+          }
+        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/python!Declaration:function(1)",