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

package/src/components/SourceFile.tsx

@@ -44,6 +44,10 @@ export interface SourceFileProps {
    * Comment to add to the header, which will be rendered as a comment in the file.
    */
   headerComment?: string;
+  /**
+   * Documentation for this module, which will be rendered as a module-level docstring.
+   */
+  doc?: Children;
 }
 
 /**
@@ -62,6 +66,26 @@ export interface SourceFileProps {
  * def test():
  *   pass
  * ```
+ *
+ * @example
+ * With module documentation:
+ * ```tsx
+ * <SourceFile
+ *   path="utils.py"
+ *   doc={<ModuleDoc description={[<Prose>Utility functions for data processing.</Prose>]} />}
+ * >
+ *   <FunctionDeclaration name="process_data" />
+ * </SourceFile>
+ * ```
+ * renders to
+ * ```py
+ * """
+ * Utility functions for data processing.
+ * """
+ *
+ * def process_data():
+ *   pass
+ * ```
  */
 export function SourceFile(props: SourceFileProps) {
   const directoryContext = useContext(SourceDirectoryContext)!;
@@ -83,6 +107,11 @@ export function SourceFile(props: SourceFileProps) {
         <hbr />
         <hbr />
       </Show>
+      <Show when={props.doc !== undefined}>
+        {props.doc}
+        <hbr />
+        <hbr />
+      </Show>
       <PythonSourceFileContext.Provider value={sfContext}>
         <Scope value={scope}>
           <List doubleHardline>{props.children}</List>

package/src/components/StaticMethodDeclaration.tsx

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

package/src/components/TypeArguments.tsx

@@ -0,0 +1,24 @@
+import { Children, For } from "@alloy-js/core";
+
+export interface TypeArgumentsProps {
+  args: Children[];
+}
+
+/**
+ * Render Python-style type arguments, e.g. [T, P].
+ */
+export function TypeArguments(props: TypeArgumentsProps) {
+  if (!props.args || props.args.length === 0) {
+    return undefined;
+  }
+
+  return (
+    <>
+      [
+      <For each={props.args} joiner=", ">
+        {(arg) => arg}
+      </For>
+      ]
+    </>
+  );
+}

package/src/components/TypeReference.tsx

@@ -0,0 +1,33 @@
+import { Children, Refkey, Show } from "@alloy-js/core";
+import { TypeArguments } from "./TypeArguments.js";
+
+export interface TypeReferenceProps {
+  /** A refkey to a declared symbol. */
+  refkey?: Refkey;
+  /** A raw name to reference when no refkey is provided. */
+  name?: Children;
+  /** Type arguments to render inside brackets. */
+  typeArgs?: Children[];
+}
+
+/**
+ * A type reference like Foo[T, P] or int.
+ */
+export function TypeReference(props: TypeReferenceProps) {
+  const type = props.refkey ? props.refkey : props.name;
+  const typeArgs =
+    props.typeArgs && props.typeArgs.length ?
+      <TypeArguments args={props.typeArgs} />
+    : undefined;
+
+  return (
+    <group>
+      <indent>
+        <sbr />
+        {type}
+        <Show when={Boolean(typeArgs)}>{typeArgs}</Show>
+      </indent>
+      <sbr />
+    </group>
+  );
+}

package/src/components/UnionTypeExpression.tsx

@@ -1,29 +1,18 @@
-import { Children, childrenArray, For, memo } from "@alloy-js/core";
+import { Children, For, childrenArray } from "@alloy-js/core";
 
 export interface UnionTypeExpressionProps {
-  children: Children[];
-  optional?: boolean;
+  children: Children;
 }
 
 export function UnionTypeExpression(props: UnionTypeExpressionProps) {
-  const resolvedChildren = memo(() => {
-    const children = childrenArray(() => props.children, {
-      preserveFragments: true,
-    });
-
-    if (props.optional) {
-      children.push("None");
-    }
-    return children;
-  });
-
+  const items = childrenArray(() => props.children);
   return (
     <group>
       <ifBreak>(</ifBreak>
       <indent>
         <sbr />
         <For
-          each={resolvedChildren}
+          each={items}
           joiner={
             <>
               <br />|{" "}

package/src/components/VariableDeclaration.tsx

@@ -4,13 +4,12 @@ import {
   Name,
   Show,
   createSymbolSlot,
-  emitSymbol,
   memo,
 } from "@alloy-js/core";
 import { createPythonSymbol } from "../symbol-creation.js";
 import { Atom } from "./Atom.jsx";
 import { BaseDeclarationProps } from "./Declaration.jsx";
-import { SimpleCommentBlock } from "./index.js";
+import { SimpleCommentBlock } from "./PyDoc.jsx";
 
 export interface VariableDeclarationProps extends BaseDeclarationProps {
   /**
@@ -89,7 +88,6 @@ export function VariableDeclaration(props: VariableDeclarationProps) {
     ValueTypeSymbolSlot.moveMembersTo(sym);
   }
 
-  emitSymbol(sym);
   // Handle optional type annotation
   const type = memo(() => {
     if (!props.type || props.callStatementVar) return undefined;

package/src/components/index.ts

@@ -2,19 +2,29 @@ export * from "./Atom.js";
 export * from "./CallSignature.js";
 export * from "./ClassDeclaration.js";
 export * from "./ClassInstantiation.js";
+export * from "./ClassMethodDeclaration.js";
+export * from "./ConstructorDeclaration.js";
 export * from "./Declaration.js";
+export * from "./DunderMethodDeclaration.js";
 export * from "./EnumDeclaration.js";
 export * from "./EnumMember.js";
+export type { CommonFunctionProps } from "./FunctionBase.js";
 export * from "./FunctionCallExpression.js";
 export * from "./FunctionDeclaration.js";
 export * from "./ImportStatement.js";
 export * from "./LexicalScope.js";
 export * from "./MemberExpression.js";
 export * from "./MemberScope.jsx";
+export type { MethodDeclarationBaseProps } from "./MethodBase.js";
+export * from "./MethodDeclaration.js";
+export * from "./PropertyDeclaration.js";
 export * from "./PyDoc.js";
 export * from "./PythonBlock.js";
 export * from "./Reference.js";
 export * from "./SourceFile.js";
 export * from "./StatementList.js";
+export * from "./StaticMethodDeclaration.js";
+export * from "./TypeArguments.js";
+export * from "./TypeReference.js";
 export * from "./UnionTypeExpression.js";
 export * from "./VariableDeclaration.js";

package/src/parameter-descriptor.ts

@@ -19,11 +19,6 @@ export interface ParameterDescriptor {
    */
   readonly refkey?: Refkey | Refkey[];
 
-  /**
-   * Whether the parameter is optional.
-   */
-  readonly optional?: boolean;
-
   /**
    * Documentation for the parameter.
    */
@@ -34,3 +29,9 @@ export interface ParameterDescriptor {
    */
   readonly default?: Children;
 }
+
+export function isParameterDescriptor(
+  param: unknown,
+): param is ParameterDescriptor {
+  return typeof param === "object" && param !== null && "name" in param;
+}

package/src/symbol-creation.ts

@@ -18,6 +18,22 @@ interface CreatePythonSymbolOptions extends PythonOutputSymbolOptions {
   space?: OutputSpace;
   instance?: boolean;
 }
+
+/**
+ * Attempts to find an existing symbol by name in the target space.
+ */
+export function findExistingSymbol(
+  name: string,
+  targetSpace?: OutputSpace,
+): PythonOutputSymbol | undefined {
+  if (!targetSpace) {
+    return undefined;
+  }
+
+  const existingSymbol = targetSpace.symbolNames.get(name);
+  return existingSymbol as PythonOutputSymbol | undefined;
+}
+
 /**
  * Creates a symbol for a python declaration in the current scope.
  */
@@ -55,6 +71,7 @@ export function createPythonSymbol(
     metadata: options.metadata,
     module: sfContext?.module,
     type: options.type,
+    ignoreNameConflict: options.ignoreNameConflict,
     namePolicy: usePythonNamePolicy().for(kind),
   });
 }

package/src/symbols/factories.ts

@@ -0,0 +1,39 @@
+import { Namekey } from "@alloy-js/core";
+import { createPythonSymbol } from "../symbol-creation.js";
+import type { PythonOutputSymbol } from "./python-output-symbol.js";
+import { usePythonScope } from "./scopes.js";
+
+/**
+ * Creates a function symbol in the current scope.
+ */
+export function createFunctionSymbol(
+  name: string | Namekey,
+  options: { refkeys?: any } = {},
+): PythonOutputSymbol {
+  return createPythonSymbol(
+    name,
+    { instance: false, refkeys: options.refkeys },
+    "function",
+  );
+}
+
+/**
+ * Creates a method symbol in a class. Validates that the current scope is a member scope.
+ */
+export function createMethodSymbol(
+  name: string | Namekey,
+  options: { refkeys?: any } = {},
+): PythonOutputSymbol {
+  const scope = usePythonScope();
+  if (!scope?.isMemberScope) {
+    const displayName = typeof name === "string" ? name : name.name;
+    throw new Error(
+      `Method "${displayName}" must be declared inside a class (member scope)`,
+    );
+  }
+  return createPythonSymbol(
+    name,
+    { instance: true, refkeys: options.refkeys },
+    "function",
+  );
+}

package/src/symbols/index.ts

@@ -1,3 +1,4 @@
+export * from "./factories.js";
 export * from "./python-lexical-scope.js";
 export * from "./python-member-scope.js";
 export * from "./python-module-scope.js";

package/src/symbols/reference.tsx

@@ -9,11 +9,9 @@ import {
 } from "@alloy-js/core";
 import { MemberExpression } from "../components/MemberExpression.jsx";
 import { PythonSourceFileContext } from "../components/SourceFile.jsx";
-import {
-  PythonModuleScope,
-  PythonOutputScope,
-  PythonOutputSymbol,
-} from "./index.js";
+import { PythonModuleScope } from "./python-module-scope.js";
+import { PythonOutputSymbol } from "./python-output-symbol.js";
+import { PythonOutputScope } from "./scopes.js";
 
 export function ref(
   refkey: Refkey,

package/src/utils.ts

@@ -14,8 +14,6 @@ export function getCallSignatureProps(
     "typeParameters",
     "args",
     "kwargs",
-    "instanceFunction",
-    "classFunction",
     "returnType",
   ]);