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

package/src/components/CallSignature.tsx

@@ -5,20 +5,19 @@ import {
   For,
   Show,
   SymbolSlot,
-  useContext,
 } from "@alloy-js/core";
-import { ParameterDescriptor } from "../parameter-descriptor.js";
+import {
+  isParameterDescriptor,
+  ParameterDescriptor,
+} from "../parameter-descriptor.js";
 import { createPythonSymbol } from "../symbol-creation.js";
 import { PythonOutputSymbol } from "../symbols/index.js";
 import { Atom } from "./Atom.jsx";
-import { PythonSourceFileContext } from "./SourceFile.jsx";
 
 export interface CallSignatureParametersProps {
-  readonly parameters?: ParameterDescriptor[] | string[];
+  readonly parameters?: (ParameterDescriptor | string)[];
   readonly args?: boolean;
   readonly kwargs?: boolean;
-  readonly instanceFunction?: boolean;
-  readonly classFunction?: boolean;
 }
 
 /**
@@ -35,33 +34,10 @@ export interface CallSignatureParametersProps {
  * ```
  */
 export function CallSignatureParameters(props: CallSignatureParametersProps) {
-  // Validate that only one of instanceFunction or classFunction is true
-  if (props.instanceFunction && props.classFunction) {
-    throw new Error("Cannot be both an instance function and a class function");
-  }
-
-  const sfContext = useContext(PythonSourceFileContext);
-  const module = sfContext?.module;
   const parameters = normalizeAndDeclareParameters(props.parameters ?? []);
 
   const parameterList = computed(() => {
     const params = [];
-
-    // Add self/cls parameter if instance or class function
-    if (props.instanceFunction) {
-      params.push(
-        parameter({
-          symbol: createPythonSymbol("self", { module: module }),
-        }),
-      );
-    } else if (props.classFunction) {
-      params.push(
-        parameter({
-          symbol: createPythonSymbol("cls", { module: module }),
-        }),
-      );
-    }
-
     // Add regular parameters
     parameters.forEach((param) => {
       params.push(parameter(param));
@@ -95,16 +71,7 @@ function parameter(param: DeclaredParameterDescriptor) {
       <Show when={!!param.type}>
         : <TypeSlot>{param.type}</TypeSlot>
       </Show>
-      <Show when={!!param.optional}>
-        <Show when={!param.type}>=</Show>
-        <Show when={!!param.type}> = </Show>
-        <>
-          {param.default ?
-            <Atom jsValue={param.default} />
-          : "None"}
-        </>
-      </Show>
-      <Show when={!param.optional && param.default !== undefined}>
+      <Show when={param.default !== undefined}>
         <Show when={!param.type}>=</Show>
         <Show when={!!param.type}> = </Show>
         <>
@@ -122,19 +89,10 @@ interface DeclaredParameterDescriptor
 }
 
 function normalizeAndDeclareParameters(
-  parameters: ParameterDescriptor[] | string[],
+  parameters: (ParameterDescriptor | string)[],
 ): DeclaredParameterDescriptor[] {
-  if (parameters.length === 0) {
-    return [];
-  }
-  if (typeof parameters[0] === "string") {
-    return (parameters as string[]).map((paramName) => {
-      const symbol = createPythonSymbol(paramName, {}, "parameter");
-
-      return { refkeys: symbol.refkeys, symbol };
-    });
-  } else {
-    return (parameters as ParameterDescriptor[]).map((param) => {
+  return parameters.map((param) => {
+    if (isParameterDescriptor(param)) {
       const TypeSlot = createSymbolSlot();
 
       const symbol = createPythonSymbol(
@@ -151,17 +109,19 @@ function normalizeAndDeclareParameters(
         symbol,
         TypeSlot,
       };
-    });
-  }
+    } else {
+      const symbol = createPythonSymbol(param, {}, "parameter");
+      return { refkeys: symbol.refkeys, 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. Otherwise, it's an array of
-   * {@link ParameterDescriptor}s.
+   * 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.
    */
-  parameters?: ParameterDescriptor[] | string[];
+  parameters?: (ParameterDescriptor | string)[];
 
   /**
    * The type parameters of the call signature, e.g. for a generic function.
@@ -179,16 +139,6 @@ export interface CallSignatureProps {
    */
   kwargs?: boolean;
 
-  /**
-   * Indicates that this is an instance function.
-   */
-  instanceFunction?: boolean; // true if this is an instance function
-
-  /**
-   * Indicates that this is a class function.
-   */
-  classFunction?: boolean; // true if this is a class function
-
   /**
    * The return type of the function.
    */
@@ -221,8 +171,6 @@ export function CallSignature(props: CallSignatureProps) {
       parameters={props.parameters}
       args={props.args}
       kwargs={props.kwargs}
-      instanceFunction={props.instanceFunction}
-      classFunction={props.classFunction}
     />
   );
   const typeParams =

package/src/components/ClassMethodDeclaration.tsx

@@ -0,0 +1,34 @@
+import { createMethodSymbol } from "../symbols/factories.js";
+import type { CommonFunctionProps } from "./FunctionBase.js";
+import { MethodDeclarationBase } from "./MethodBase.js";
+
+/**
+ * A Python class method declaration component.
+ *
+ * @example
+ * ```tsx
+ * <py.ClassMethodDeclaration name="create" parameters={[{ name: "value", type: "str" }]}>
+ *   return cls(value)
+ * </py.ClassMethodDeclaration>
+ * ```
+ * Generates:
+ * ```python
+ * @classmethod
+ * def create(cls, value: str) -> None:
+ *     return cls(value)
+ * ```
+ */
+export interface ClassMethodDeclarationProps extends CommonFunctionProps {
+  abstract?: boolean;
+}
+
+export function ClassMethodDeclaration(props: ClassMethodDeclarationProps) {
+  const sym = createMethodSymbol(props.name, { refkeys: props.refkey });
+  return (
+    <>
+      {"@classmethod"}
+      <hbr />
+      <MethodDeclarationBase functionType="class" {...props} sym={sym} />
+    </>
+  );
+}

package/src/components/ConstructorDeclaration.tsx

@@ -0,0 +1,37 @@
+import { namekey } from "@alloy-js/core";
+import { createMethodSymbol } from "../symbols/factories.js";
+import type { CommonFunctionProps } from "./FunctionBase.js";
+import { MethodDeclarationBase } from "./MethodBase.js";
+
+/**
+ * A Python constructor declaration for `__new__`.
+ *
+ * @example
+ * ```tsx
+ * <py.ConstructorDeclaration parameters={[{ name: "value", type: "int" }]}>
+ *   pass
+ * </py.ConstructorDeclaration>
+ * ```
+ * Generates:
+ * ```python
+ * def __new__(cls, value: int):
+ *     pass
+ * ```
+ */
+export interface ConstructorDeclarationProps
+  extends Omit<CommonFunctionProps, "name"> {
+  abstract?: boolean;
+}
+
+export function ConstructorDeclaration(props: ConstructorDeclarationProps) {
+  const name = namekey("__new__", { ignoreNamePolicy: true });
+  const sym = createMethodSymbol(name, { refkeys: props.refkey });
+  return (
+    <MethodDeclarationBase
+      {...props}
+      name={name}
+      functionType="class"
+      sym={sym}
+    />
+  );
+}

package/src/components/DunderMethodDeclaration.tsx

@@ -0,0 +1,30 @@
+import { isNamekey, namekey } from "@alloy-js/core";
+import type { CommonFunctionProps } from "./FunctionBase.js";
+import { MethodDeclaration } from "./MethodDeclaration.js";
+
+/**
+ * A Python dunder method declaration.
+ *
+ * @example
+ * ```tsx
+ * <py.DunderMethodDeclaration name="__repr__" returnType="str">
+ *   return f"<MyType>"
+ * </py.DunderMethodDeclaration>
+ * ```
+ * Generates:
+ * ```python
+ * def __repr__(self) -> str:
+ *     return f"<MyType>"
+ * ```
+ */
+export interface DunderMethodDeclarationProps extends CommonFunctionProps {
+  abstract?: boolean;
+}
+
+export function DunderMethodDeclaration(props: DunderMethodDeclarationProps) {
+  const finalName =
+    isNamekey(props.name) ?
+      props.name
+    : namekey(props.name as string, { ignoreNamePolicy: true });
+  return <MethodDeclaration {...props} name={finalName} />;
+}

package/src/components/EnumDeclaration.tsx

@@ -8,11 +8,10 @@ import { enumModule } from "../builtins/python.js";
 import { createPythonSymbol } from "../symbol-creation.js";
 import { BaseDeclarationProps } from "./Declaration.js";
 import { EnumMember, EnumMemberProps } from "./EnumMember.js";
-import { SimpleCommentBlock } from "./index.js";
 import { MemberScope } from "./MemberScope.jsx";
 import { PythonBlock } from "./PythonBlock.jsx";
 
-export interface EnumProps extends BaseDeclarationProps {
+export interface EnumPropsBase extends BaseDeclarationProps {
   /**
    * The base type of the enum. One of: 'Enum', 'IntEnum', 'StrEnum', 'Flag', 'IntFlag'.
    * Defaults to 'Enum'.
@@ -22,47 +21,13 @@ export interface EnumProps extends BaseDeclarationProps {
    * Members of the enum as an array of objects.
    */
   members?: Array<EnumMemberProps>;
-  /**
-   * The enum style: 'classic' (default), 'auto', or 'functional'.
-   */
-  style?: "classic" | "auto" | "functional";
   /**
    * Optional docstring for the enum.
    */
   doc?: Children;
 }
 
-/**
- * A Python enum declaration, following https://docs.python.org/3.11/library/enum.html.
- *
- * @example
- * ```tsx
- * <EnumDeclaration name="Direction" style="functional">
- *   members={[
- *     { name: "NORTH" },
- *     { name: "SOUTH" },
- *     { name: "EAST" },
- *     { name: "WEST" },
- *   ]}
- * />
- * ```
- * This will generate:
- * ```python
- * from enum import Enum
- * class Direction(Enum):
- *     NORTH = "NORTH"
- *     SOUTH = "SOUTH"
- *     EAST = "EAST"
- *     WEST = "WEST"
- * ```
- */
-export function EnumDeclaration(props: EnumProps) {
-  // Handle enum styles
-  if (props.style === "functional") {
-    return <FunctionalEnumDeclaration {...props} />;
-  }
-  return <ClassEnumDeclaration {...props} />;
-}
+export interface FunctionalEnumProps extends EnumPropsBase {}
 
 /**
  * Create a Python enum using the functional syntax.
@@ -105,7 +70,7 @@ export function EnumDeclaration(props: EnumProps) {
  * Status = Enum('Status', {'PENDING': 1, 'ACTIVE': 2, 'INACTIVE': 3})
  * ```
  */
-export function FunctionalEnumDeclaration(props: EnumProps) {
+export function FunctionalEnumDeclaration(props: FunctionalEnumProps) {
   const sym = createPythonSymbol(
     props.name,
     {
@@ -143,6 +108,13 @@ export function FunctionalEnumDeclaration(props: EnumProps) {
   );
 }
 
+export interface ClassEnumProps extends EnumPropsBase {
+  /**
+   * Indicates that the enum members should be auto-generated.
+   */
+  auto?: boolean;
+}
+
 /**
  * Create a Python enum using the class-based syntax.
  *
@@ -212,7 +184,7 @@ export function FunctionalEnumDeclaration(props: EnumProps) {
  *     BLUE = auto()
  * ```
  */
-export function ClassEnumDeclaration(props: EnumProps) {
+export function ClassEnumDeclaration(props: ClassEnumProps) {
   const baseType = props.baseType || "Enum";
   const sym = createPythonSymbol(
     props.name,
@@ -224,20 +196,20 @@ export function ClassEnumDeclaration(props: EnumProps) {
   let memberList: Array<EnumMemberProps> = (props.members ?? []).map((m) =>
     m.value === undefined ? { ...m, auto: false } : m,
   );
-  if (props.style === "auto") {
+  if (props.auto) {
     memberList = memberList.map((m) =>
       m.value === undefined ? { name: m.name, auto: true } : m,
     );
   }
   return (
     <CoreDeclaration symbol={sym}>
-      <Show when={Boolean(props.doc)}>
-        <SimpleCommentBlock children={props.doc} />
-        <hbr />
-      </Show>
       class {sym.name}({enumModule["."][baseType]})
       <MemberScope ownerSymbol={sym}>
         <PythonBlock opener=":">
+          <Show when={Boolean(props.doc)}>
+            {props.doc}
+            <hbr />
+          </Show>
           <For each={memberList} hardline>
             {(member) => (
               <EnumMember

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 { SimpleInlineComment } from "./index.js";
+import { SimpleInlineMemberComment } 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}>
-          <SimpleInlineComment>{props.doc}</SimpleInlineComment>
+          <SimpleInlineMemberComment>{props.doc}</SimpleInlineMemberComment>
         </Show>
       </>
     );
@@ -83,7 +83,7 @@ export function EnumMember(props: EnumMemberProps) {
       {sym.name}
       <Show when={valueCode !== undefined}> = {valueCode}</Show>
       <Show when={props.doc !== undefined}>
-        <SimpleInlineComment>{props.doc}</SimpleInlineComment>
+        <SimpleInlineMemberComment>{props.doc}</SimpleInlineMemberComment>
       </Show>
     </>
   );

package/src/components/FunctionBase.tsx

@@ -0,0 +1,88 @@
+import { Name, Show } from "@alloy-js/core";
+import { PythonOutputSymbol } from "../index.js";
+import { getCallSignatureProps } from "../utils.js";
+import { CallSignature, CallSignatureProps } from "./CallSignature.jsx";
+import { BaseDeclarationProps, Declaration } from "./Declaration.js";
+import { LexicalScope } from "./LexicalScope.jsx";
+import { PythonBlock } from "./PythonBlock.jsx";
+
+/**
+ * Shared base interface for function-like components.
+ *
+ * @remarks
+ * This interface is consumed by public components like `FunctionDeclaration`,
+ * `MethodDeclaration`, and property method helpers. It combines declaration
+ * metadata with call signature shape.
+ */
+export interface CommonFunctionProps
+  extends BaseDeclarationProps,
+    CallSignatureProps {
+  /** Indicates that the function is async. */
+  async?: boolean;
+}
+
+/**
+ * Props for `BaseFunctionDeclaration`.
+ *
+ * @remarks
+ * This low-level component powers function/method-like declarations by
+ * handling symbol creation, parameter injection for instance/class methods,
+ * and common rendering concerns. Intended primarily for internal reuse.
+ */
+export interface BaseFunctionDeclarationProps extends CommonFunctionProps {
+  /** Indicates the type of function. */
+  functionType?: "instance" | "class" | "static";
+  /** Pre-created symbol to render. Must be provided by caller. */
+  sym: PythonOutputSymbol;
+}
+
+/**
+ * Base function declaration that handles instance/class/static parameter injection
+ * and symbol creation. Exported for internal reuse by method-like components.
+ *
+ * @example
+ * ```tsx
+ * // Not typically used directly. Prefer higher-level components.
+ * <BaseFunctionDeclaration name="helper" parameters={[{ name: "x" }]}>
+ *   return x
+ * </BaseFunctionDeclaration>
+ * ```
+ * Generates:
+ * ```python
+ * def helper(x):
+ *     return x
+ * ```
+ */
+export function BaseFunctionDeclaration(props: BaseFunctionDeclarationProps) {
+  const asyncKwd = props.async ? "async " : "";
+  let parameters;
+  switch (props.functionType) {
+    case "instance":
+      parameters = [{ name: "self" }, ...(props.parameters || [])];
+      break;
+    case "class":
+      parameters = [{ name: "cls" }, ...(props.parameters || [])];
+      break;
+    default:
+      parameters = props.parameters;
+  }
+  const sym: PythonOutputSymbol = props.sym;
+
+  return (
+    <>
+      <Declaration {...props} nameKind="function" symbol={sym}>
+        {asyncKwd}def <Name />
+        <LexicalScope name={sym.name}>
+          <CallSignature
+            {...getCallSignatureProps(props, {})}
+            parameters={parameters}
+          />
+          <PythonBlock opener=":">
+            <Show when={Boolean(props.doc)}>{props.doc}</Show>
+            {props.children ?? "pass"}
+          </PythonBlock>
+        </LexicalScope>
+      </Declaration>
+    </>
+  );
+}

package/src/components/FunctionDeclaration.tsx

@@ -1,16 +1,11 @@
-import { emitSymbol, Name, namekey, Show } from "@alloy-js/core";
-import { createPythonSymbol } from "../symbol-creation.js";
-import { getCallSignatureProps } from "../utils.js";
-import { CallSignature, CallSignatureProps } from "./CallSignature.jsx";
-import { BaseDeclarationProps, Declaration } from "./Declaration.js";
-import { PythonBlock } from "./PythonBlock.jsx";
-import { LexicalScope } from "./index.js";
+import { createFunctionSymbol } from "../symbols/factories.js";
+import type { CommonFunctionProps } from "./FunctionBase.js";
+import { BaseFunctionDeclaration } from "./FunctionBase.js";
 
-export interface FunctionDeclarationProps
-  extends BaseDeclarationProps,
-    CallSignatureProps {
-  async?: boolean;
-}
+// Types are sourced from FunctionBase to avoid duplicate exports
+
+// Clean public interface extending common properties
+export interface FunctionDeclarationProps extends CommonFunctionProps {}
 
 /**
  * A Python function declaration.
@@ -18,84 +13,25 @@ export interface FunctionDeclarationProps
  * @example
  * ```tsx
  * <FunctionDeclaration
- *  name="my_function"
- *  returnType="int"
- *  parameters=[{name: "a", type: "int"},{name: "b", type: "str"}]>
+ *   name="my_function"
+ *   returnType="int"
+ *   parameters={[{ name: "a", type: { children: "int" } }, { name: "b", type: { children: "str" } }]}
+ * >
  *   return a + b
  * </FunctionDeclaration>
  * ```
  * This will generate:
  * ```python
  * def my_function(a: int, b: str) -> int:
- *   return a + b
- * ```
- */
-export function FunctionDeclaration(props: FunctionDeclarationProps) {
-  const asyncKwd = props.async ? "async " : "";
-  const callSignatureProps = getCallSignatureProps(props, {});
-  const sym = createPythonSymbol(
-    props.name,
-    {
-      instance: props.instanceFunction,
-      refkeys: props.refkey,
-    },
-    "function",
-  );
-  emitSymbol(sym);
-
-  return (
-    <>
-      <Declaration {...props} nameKind="function" symbol={sym}>
-        {asyncKwd}def <Name />
-        <LexicalScope name={sym.name}>
-          <CallSignature
-            {...callSignatureProps}
-            returnType={props.returnType}
-          />
-          <PythonBlock opener=":">
-            <Show when={Boolean(props.doc)}>{props.doc}</Show>
-            {props.children ?? "pass"}
-          </PythonBlock>
-        </LexicalScope>
-      </Declaration>
-    </>
-  );
-}
-
-export interface InitFunctionDeclarationProps
-  extends Omit<
-    FunctionDeclarationProps,
-    "name" | "instanceFunction" | "classFunction"
-  > {}
-
-/**
- * A Python `__init__` function declaration.
- *
- * @example
- * ```tsx
- * <InitFunctionDeclaration>
- *   self.attribute = "value"
- * </InitFunctionDeclaration>
- * ```
- * This will generate:
- * ```python
- * def __init__(self: MyClass) -> None:
- *     self.attribute = "value"
+ *     return a + b
  * ```
  *
  * @remarks
- *
- * This is a convenience component that sets the name to `__init__`, marks it as
- * an instance function, and forces the name to be `__init__` without applying
- * the name policy.
+ * This component creates a Python function declaration with optional type annotations,
+ * parameters, and return types. It supports async functions and automatically
+ * handles symbol creation and emission.
  */
-export function InitFunctionDeclaration(props: InitFunctionDeclarationProps) {
-  return (
-    <FunctionDeclaration
-      {...props}
-      name={namekey("__init__", { ignoreNamePolicy: true })}
-      instanceFunction={true}
-      classFunction={false}
-    />
-  );
+export function FunctionDeclaration(props: FunctionDeclarationProps) {
+  const sym = createFunctionSymbol(props.name, { refkeys: props.refkey });
+  return <BaseFunctionDeclaration {...props} sym={sym} />;
 }

package/src/components/MethodBase.tsx

@@ -0,0 +1,53 @@
+import { abcModule } from "../builtins/python.js";
+import {
+  BaseFunctionDeclaration,
+  BaseFunctionDeclarationProps,
+  CommonFunctionProps,
+} from "./FunctionBase.js";
+
+/**
+ * Shared base props for all method-like declarations.
+ */
+export interface MethodDeclarationBaseProps extends CommonFunctionProps {
+  /** Indicates that the method is abstract. */
+  abstract?: boolean;
+}
+
+/**
+ * Internal base for method-like components.
+ *
+ * @remarks
+ * Applies `@abstractmethod` when requested and delegates to
+ * `BaseFunctionDeclaration` for the function/method body.
+ *
+ * @example
+ * ```tsx
+ * <MethodDeclarationBase name="do_work" functionType="instance">
+ *   return 1
+ * </MethodDeclarationBase>
+ * ```
+ * Generates:
+ * ```python
+ * def do_work(self):
+ *     return 1
+ * ```
+ */
+export function MethodDeclarationBase(
+  props: MethodDeclarationBaseProps &
+    Pick<BaseFunctionDeclarationProps, "functionType" | "sym">,
+) {
+  const abstractMethod =
+    props.abstract ?
+      <>
+        @{abcModule["."].abstractmethod}
+        <hbr />
+      </>
+    : undefined;
+
+  return (
+    <>
+      {abstractMethod}
+      <BaseFunctionDeclaration {...props} />
+    </>
+  );
+}

package/src/components/MethodDeclaration.tsx

@@ -0,0 +1,27 @@
+import { createMethodSymbol } from "../symbols/factories.js";
+import type { MethodDeclarationBaseProps } from "./MethodBase.js";
+import { MethodDeclarationBase } from "./MethodBase.js";
+
+/**
+ * A Python instance method declaration component.
+ *
+ * @example
+ * ```tsx
+ * <py.MethodDeclaration name="do_work" parameters={[{ name: "value", type: "int" }]}>
+ *   return value * 2
+ * </py.MethodDeclaration>
+ * ```
+ * Generates:
+ * ```python
+ * def do_work(self, value: int) -> None:
+ *     return value * 2
+ * ```
+ *
+ * @remarks
+ * Automatically injects the `self` parameter for instance methods and enforces
+ * that the declaration appears within a class body.
+ */
+export function MethodDeclaration(props: MethodDeclarationBaseProps) {
+  const sym = createMethodSymbol(props.name, { refkeys: props.refkey });
+  return <MethodDeclarationBase functionType="instance" {...props} sym={sym} />;
+}