@alloy-js/python 0.0.1

package/src/components/NoNamePolicy.tsx

@@ -0,0 +1,31 @@
+import { NamePolicyContext } from "@alloy-js/core";
+import { Children } from "@alloy-js/core/jsx-runtime";
+
+export interface NoNamePolicyProps {
+  children: Children;
+}
+
+/**
+ * A wrapper component that disables name policy transformation for its children.
+ *
+ * This is useful for components that need to preserve exact names without applying
+ * naming conventions, such as Python dunder methods like `__init__`, `__str__`, etc.
+ *
+ * @example
+ * ```tsx
+ * <NoNamePolicy>
+ *   <FunctionDeclaration name="__init__" instanceFunction>
+ *     // Function content
+ *   </FunctionDeclaration>
+ * </NoNamePolicy>
+ * ```
+ *
+ * This ensures `__init__` stays as `__init__` without name policy transformation.
+ */
+export function NoNamePolicy(props: NoNamePolicyProps) {
+  return (
+    <NamePolicyContext.Provider value={undefined}>
+      {props.children}
+    </NamePolicyContext.Provider>
+  );
+}

package/src/components/PyDoc.tsx

@@ -0,0 +1,331 @@
+import { For, Indent, List, Prose, Show, childrenArray } from "@alloy-js/core";
+import { Children } from "@alloy-js/core/jsx-runtime";
+import { ParameterDescriptor } from "../parameter-descriptor.js";
+import { Atom } from "./index.js";
+
+interface GoogleStyleDocParamTypeProps {
+  type?: Children;
+  optional?: boolean;
+}
+
+function GoogleStyleDocParamType(props: GoogleStyleDocParamTypeProps) {
+  return (
+    <>
+      <Show when={Boolean(props.type)}>
+        {" ("}
+        {props.type}
+        <Show when={props.optional}>{", optional"}</Show>
+        {")"}
+      </Show>
+    </>
+  );
+}
+
+interface GoogleStyleDocParamNameProps {
+  name: Children;
+}
+
+function GoogleStyleDocParamName(props: GoogleStyleDocParamNameProps) {
+  return <>{props.name}</>;
+}
+
+interface GoogleStyleDocParamDescriptionProps {
+  children?: Children;
+  defaultValue?: Children;
+}
+
+function GoogleStyleDocParamDescription(
+  props: GoogleStyleDocParamDescriptionProps,
+) {
+  return (
+    <Show when={Boolean(props.children)}>
+      {": "}
+      <align width={4}>
+        <Prose>{props.children}</Prose>
+        <Show when={Boolean(props.defaultValue)}>
+          {" "}
+          Defaults to <Atom jsValue={props.defaultValue}></Atom>.
+        </Show>
+      </align>
+    </Show>
+  );
+}
+
+export interface GoogleStyleDocParamProps {
+  name: Children;
+  type?: Children;
+  children?: Children;
+  optional?: boolean;
+  defaultValue?: Children;
+}
+
+/**
+ * Create a GoogleStyleDoc parameter.
+ */
+export function GoogleStyleDocParam(props: GoogleStyleDocParamProps) {
+  return (
+    <>
+      <GoogleStyleDocParamName name={props.name} />
+      <GoogleStyleDocParamType type={props.type} optional={props.optional} />
+      <GoogleStyleDocParamDescription
+        children={props.children}
+        defaultValue={props.defaultValue}
+      />
+    </>
+  );
+}
+
+export interface GoogleStyleDocParamsProps {
+  parameters: ParameterDescriptor[] | string[];
+}
+
+/**
+ * A component that creates a GoogleStyleDoc block for parameters.
+ */
+export function GoogleStyleDocParams(props: GoogleStyleDocParamsProps) {
+  const parameters = normalizeParametersForDoc(props.parameters);
+  return (
+    <>
+      {"Args:"}
+      <Indent>
+        <List doubleHardline>
+          {parameters.map((param) => (
+            <GoogleStyleDocParam
+              name={param.name}
+              type={param.type}
+              optional={param.optional}
+            >
+              {param.doc}
+            </GoogleStyleDocParam>
+          ))}
+        </List>
+      </Indent>
+    </>
+  );
+}
+
+export interface GoogleStyleDocReturnProps {
+  message: string;
+}
+
+/**
+ * A component that creates a GoogleStyleDoc block for parameters.
+ */
+export function GoogleStyleDocReturn(props: GoogleStyleDocReturnProps) {
+  return (
+    <>
+      {"Returns:"}
+      <Indent>{props.message}</Indent>
+    </>
+  );
+}
+
+export interface GoogleStyleDocRaisesProps {
+  message: string;
+}
+
+/**
+ * A component that creates a GoogleStyleDoc block for parameters.
+ */
+export function GoogleStyleDocRaises(props: GoogleStyleDocRaisesProps) {
+  return (
+    <>
+      {"Raises:"}
+      <Indent>{props.message}</Indent>
+    </>
+  );
+}
+
+export interface GoogleStyleFunctionDocProps
+  extends Omit<FunctionDocProps, "style"> {}
+
+/**
+ * A component that creates a GoogleStyleFunctionDoc block for parameters.
+ */
+export function GoogleStyleFunctionDoc(props: GoogleStyleFunctionDocProps) {
+  // We are creating a list instead of relying on <Show> because otherwise
+  // <List> would render spaces between the elements even if <Show> evaluates to false.
+  const children = [];
+  if (props.description !== undefined) {
+    children.push(
+      <List doubleHardline>{props.description.map((param) => param)}</List>,
+    );
+  }
+  if (props.parameters !== undefined && props.parameters.length > 0) {
+    children.push(<GoogleStyleDocParams parameters={props.parameters} />);
+  }
+  if (props.returns !== undefined) {
+    children.push(<GoogleStyleDocReturn message={props.returns} />);
+  }
+  if (props.raises !== undefined && props.raises.length > 0) {
+    children.push(
+      props.raises!.map((param) => <GoogleStyleDocRaises message={param} />),
+    );
+  }
+  return <PyDoc>{children}</PyDoc>;
+}
+
+export interface FunctionDocProps {
+  description: Children[];
+  parameters?: ParameterDescriptor[] | string[];
+  returns?: string;
+  raises?: string[];
+  style?: "google";
+}
+
+/**
+ * A component that creates a FunctionDoc block for parameters.
+ */
+export function FunctionDoc(props: FunctionDocProps) {
+  const style = props.style ?? "google";
+  if (style === "google") {
+    return (
+      <GoogleStyleFunctionDoc
+        description={props.description}
+        parameters={props.parameters}
+        returns={props.returns}
+        raises={props.raises}
+      />
+    );
+  }
+}
+
+export interface ClassDocProps {
+  description: Children[];
+  parameters?: ParameterDescriptor[] | string[];
+  style?: "google";
+}
+
+/**
+ * A component that creates a ClassDoc block for parameters.
+ */
+export function ClassDoc(props: ClassDocProps) {
+  const style = props.style ?? "google";
+  if (style === "google") {
+    return (
+      <GoogleStyleClassDoc
+        description={props.description}
+        parameters={props.parameters}
+      />
+    );
+  }
+}
+
+export interface GoogleStyleClassDocProps
+  extends Omit<ClassDocProps, "style"> {}
+
+/**
+ * A component that creates a GoogleStyleClassDoc block for parameters.
+ */
+export function GoogleStyleClassDoc(props: GoogleStyleClassDocProps) {
+  // We are creating a list instead of relying on <Show> because otherwise
+  // <List> would render spaces between the elements even if <Show> evaluates to false.
+  const children = [];
+  if (props.description !== undefined) {
+    children.push(
+      <List doubleHardline>{props.description.map((param) => param)}</List>,
+    );
+  }
+  if (props.parameters !== undefined && props.parameters.length > 0) {
+    children.push(<GoogleStyleDocParams parameters={props.parameters} />);
+  }
+  return <PyDoc>{children}</PyDoc>;
+}
+
+export interface PyDocExampleProps {
+  children: Children;
+}
+
+/**
+ * Create a PyDoc example, which is prepended by \>\>.
+ */
+export function PyDocExample(props: PyDocExampleProps) {
+  const children = childrenArray(() => props.children);
+  let lines: 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);
+  }
+
+  return (
+    <>
+      <For each={lines}>
+        {(line) => (
+          <>
+            {">> "}
+            {line}
+          </>
+        )}
+      </For>
+    </>
+  );
+}
+
+function normalizeParametersForDoc(
+  parameters: ParameterDescriptor[] | string[],
+): ParameterDescriptor[] {
+  if (parameters.some((p) => typeof p === "string")) {
+    return [];
+  }
+
+  return parameters as ParameterDescriptor[];
+}
+
+export interface PyDocProps {
+  children: Children;
+}
+
+/**
+ * A PyDoc comment. The children of this component are joined with two hard
+ * linebreaks. This is useful for creating PyDoc comments with multiple paragraphs.
+ */
+export function PyDoc(props: PyDocProps) {
+  const children = childrenArray(() => props.children);
+  return (
+    <>
+      {'"""'}
+      <hbr />
+      <List doubleHardline>{children}</List>
+      <hbr />
+      {'"""'}
+      <hbr />
+    </>
+  );
+}
+
+export interface SimpleCommentBlockProps {
+  children: Children;
+}
+
+export function SimpleCommentBlock(props: SimpleCommentBlockProps) {
+  return (
+    <>
+      #{" "}
+      <align string="# ">
+        <Prose>{props.children}</Prose>
+      </align>
+    </>
+  );
+}
+
+export interface SimpleInlineCommentProps {
+  children: Children;
+}
+
+export function SimpleInlineComment(props: SimpleInlineCommentProps) {
+  return (
+    <>
+      {"  "}# <Prose>{props.children}</Prose>
+    </>
+  );
+}

package/src/components/PythonBlock.tsx

@@ -0,0 +1,26 @@
+import { Block, Children } from "@alloy-js/core";
+
+/**
+ * A Python block component that can be used to render a block of Python code.
+ *
+ * @example
+ * ```tsx
+ * <PythonBlock opener="def my_function()">
+ *   <VariableDeclaration name="x" type="int" />
+ *   <VariableDeclaration name="y" type="str" />
+ * </PythonBlock>
+ * ```
+ * renders to
+ * ```py
+ * def my_function():
+ *   x: int = None
+ *   y: str = None
+ * ```
+ */
+export function PythonBlock(props: { children: Children; opener?: string }) {
+  return (
+    <Block opener={props.opener ?? ""} closer="">
+      {props.children}
+    </Block>
+  );
+}

package/src/components/Reference.tsx

@@ -0,0 +1,21 @@
+import { computed, emitSymbol, Refkey } from "@alloy-js/core";
+import { ref } from "../symbols/index.js";
+
+export interface ReferenceProps {
+  refkey: Refkey;
+}
+
+/**
+ * A Python reference to a symbol, such as a variable, function, or class.
+ *
+ * @remarks
+ * This component is used to render references to symbols in Python code.
+ * It takes a `refkey` prop which is the key of the symbol to reference.
+ */
+export function Reference({ refkey }: ReferenceProps) {
+  const reference = ref(refkey);
+  const symbolRef = computed(() => reference()[1]);
+
+  emitSymbol(symbolRef);
+  return <>{reference()[0]}</>;
+}

package/src/components/SourceFile.tsx

@@ -0,0 +1,93 @@
+import {
+  ComponentContext,
+  SourceFile as CoreSourceFile,
+  createNamedContext,
+  List,
+  Scope,
+  Show,
+  SourceDirectoryContext,
+  useContext,
+  type Children,
+} from "@alloy-js/core";
+import { join } from "pathe";
+import { PythonModuleScope } from "../symbols/index.js";
+import { ImportStatements } from "./ImportStatement.js";
+import { Reference } from "./Reference.js";
+
+export interface PythonSourceFileContext {
+  scope: PythonModuleScope;
+  /** The module name for this file, e.g. 'test' for test.py */
+  module: string;
+}
+
+export const PythonSourceFileContext: ComponentContext<PythonSourceFileContext> =
+  createNamedContext("@alloy-js/python SourceFile");
+
+export function useSourceFile() {
+  return useContext(PythonSourceFileContext)!;
+}
+
+export interface SourceFileProps {
+  /**
+   * The path to the file relative to the source directory.
+   */
+  path: string;
+  /**
+   * Content to add to the file, such as function definitions, class definitions, and variable declarations.
+   */
+  children?: Children;
+  /**
+   * Header comment to add to the file, which will be rendered at the top of the file.
+   */
+  header?: Children;
+  /**
+   * Comment to add to the header, which will be rendered as a comment in the file.
+   */
+  headerComment?: string;
+}
+
+/**
+ * A Python source file component that represents a Python file in the source directory.
+ * It provides a scope for the file, which is a `PythonModuleScope` that contains
+ * all the symbols defined in the file, such as functions, classes, and variables.
+ *
+ * @example
+ * ```tsx
+ * <SourceFile path="test.py">
+ *   <FunctionDeclaration name="test" />
+ * </SourceFile>
+ * ```
+ * renders to
+ * ```py
+ * def test():
+ *   pass
+ * ```
+ */
+export function SourceFile(props: SourceFileProps) {
+  const directoryContext = useContext(SourceDirectoryContext)!;
+  const currentDir = directoryContext.path;
+  // Name of the scope is derived from the file path, minus the .py extension, and with slashes replaced by dots
+  const path: string = join(currentDir, props.path)
+    .replace(/\.py$/, "")
+    .replace(/\//g, ".");
+  const scope = new PythonModuleScope(path);
+  const sfContext: PythonSourceFileContext = {
+    scope: scope,
+    module: path,
+  };
+
+  return (
+    <CoreSourceFile path={props.path} filetype="py" reference={Reference}>
+      <Show when={scope.importedModules.size > 0}>
+        <ImportStatements records={scope.importedModules} />
+        <hbr />
+        <hbr />
+      </Show>
+      <PythonSourceFileContext.Provider value={sfContext}>
+        <Scope value={scope} kind="source-file">
+          <List doubleHardline>{props.children}</List>
+        </Scope>
+      </PythonSourceFileContext.Provider>
+    </CoreSourceFile>
+  );
+}

package/src/components/StatementList.tsx

@@ -0,0 +1,28 @@
+import { Children, List } from "@alloy-js/core";
+
+export interface StatementListProps {
+  children: Children;
+}
+
+/**
+ * A Python statement list, which is a list of statements that can be rendered
+ * in a Python source file.
+ *
+ * @example
+ * ```tsx
+ * <StatementList>
+ *   <FunctionDeclaration name="test" />
+ *   <VariableDeclaration name="x" value={42} />
+ * </StatementList>
+ * ```
+ * renders to
+ * ```py
+ * def test():
+ *   pass
+ *
+ * x = 42
+ * ```
+ */
+export function StatementList(props: StatementListProps) {
+  return <List hardline>{props.children}</List>;
+}

package/src/components/VariableDeclaration.tsx

@@ -0,0 +1,180 @@
+import {
+  Children,
+  Declaration as CoreDeclaration,
+  Name,
+  OutputScope,
+  OutputSymbolFlags,
+  Show,
+  createSymbolSlot,
+  effect,
+  emitSymbol,
+  memo,
+  useMemberScope,
+  useScope,
+} 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";
+
+export interface VariableDeclarationProps extends BaseDeclarationProps {
+  /**
+   * The initial value of the variable.
+   */
+  initializer?: Children;
+  /**
+   * The type of the variable. Used only for type annotation. Optional.
+   */
+  type?: Children;
+  /**
+   * Indicates if we should omit the None assignment. Optional.
+   */
+  omitNone?: boolean;
+  /**
+   * Indicates if this is a call statement variable. Optional.
+   * This is used to handle cases where the variable is part of a call statement.
+   */
+  callStatementVar?: boolean;
+  /**
+   * Indicates if this variable is an instance variable. Optional.
+   * This is used to handle cases where the variable is part of a class instance.
+   */
+  instanceVariable?: boolean;
+}
+
+/**
+ * A variable declaration component for Python.
+ *
+ * @example
+ * ```tsx
+ * <VariableDeclaration
+ *   name="myVar"
+ *   type="int"
+ *   initializer={42}  // Initial value
+ * />
+ * <VariableDeclaration
+ *   name="myOtherVar"
+ *   type="str"
+ *   omitNone={true}
+ * />
+ * <VariableDeclaration
+ *   name="myCallStmtVar"
+ *   callStatementVar={true}
+ *   initializer={12}
+ * />
+ * VariableDeclaration
+ *   name=""
+ *   callStatementVar={true}
+ *   initializer={12}
+ * />
+ * ```
+ * renders to
+ * ```py
+ * myVar: int = 42
+ * myOtherVar: str
+ * myCallStmtVar=12
+ * 12
+ * ```
+ */
+export function VariableDeclaration(props: VariableDeclarationProps) {
+  const instanceVariable = props.instanceVariable ?? false;
+  const TypeSymbolSlot = createSymbolSlot();
+  const ValueTypeSymbolSlot = createSymbolSlot();
+  const memberScope = useMemberScope();
+  let scope: OutputScope | undefined = undefined;
+  // Only consider the member scope if this is an instance variable
+  if (memberScope !== undefined && instanceVariable) {
+    scope = memberScope.instanceMembers!;
+  } else {
+    scope = useScope();
+  }
+
+  const sym = createPythonSymbol(
+    props.name,
+    {
+      scope: scope,
+      refkeys: props.refkey,
+    },
+    "variable",
+    true,
+  );
+  emitSymbol(sym);
+  // Handle optional type annotation
+  const type = memo(() => {
+    if (!props.type || props.callStatementVar) return undefined;
+    return (
+      <>
+        : <TypeSymbolSlot>{props.type}</TypeSymbolSlot>
+      </>
+    );
+  });
+
+  effect(() => {
+    if (TypeSymbolSlot.ref.value) {
+      const takenSymbols = TypeSymbolSlot.ref.value;
+      for (const symbol of takenSymbols) {
+        // If the symbol is a type, instantiate it
+        symbol.instantiateTo(sym);
+      }
+    } else if (ValueTypeSymbolSlot.ref.value) {
+      const takenSymbols = ValueTypeSymbolSlot.ref.value;
+      for (const symbol of takenSymbols) {
+        // ignore non-transient symbols (likely not the result of an
+        // expression).
+        if (symbol.flags & OutputSymbolFlags.Transient) {
+          symbol.moveTo(sym);
+        }
+      }
+    }
+  });
+
+  // If we receive a symbol, resolve it to a name
+  const value =
+    typeof props.initializer === "object" ?
+      memo(() => props.initializer)
+    : props.initializer;
+  const assignmentOperator = props.callStatementVar ? "=" : " = ";
+  const getRightSide = () => {
+    // Early return for omitNone case
+    if (props.omitNone && props.initializer === undefined) {
+      return [false, ""];
+    }
+
+    // Handle null/undefined values
+    if (value === null || value === undefined) {
+      return [true, <>None</>];
+    }
+
+    let renderRightSideOperator = true;
+    // Call statement with no name
+    if (
+      props.callStatementVar &&
+      (props.name === undefined || props.name === "")
+    ) {
+      renderRightSideOperator = false;
+    }
+
+    // Standard assignment
+    return [
+      renderRightSideOperator,
+      <ValueTypeSymbolSlot>
+        <Atom jsValue={value} />
+      </ValueTypeSymbolSlot>,
+    ];
+  };
+  const [renderRightSideOperator, rightSide] = getRightSide();
+  return (
+    <>
+      <Show when={Boolean(props.doc)}>
+        <SimpleCommentBlock children={props.doc} />
+        <hbr />
+      </Show>
+      <CoreDeclaration symbol={sym}>
+        {<Name />}
+        {type}
+        {renderRightSideOperator && assignmentOperator}
+        {rightSide}
+      </CoreDeclaration>
+    </>
+  );
+}