@alloy-js/python 0.0.1

package/src/components/ClassDeclaration.tsx

@@ -0,0 +1,98 @@
+import {
+  Children,
+  List,
+  Name,
+  OutputSymbolFlags,
+  Scope,
+  Show,
+  childrenArray,
+  takeSymbols,
+} from "@alloy-js/core";
+import { createPythonSymbol } from "../symbol-creation.js";
+import {
+  BaseDeclarationProps,
+  Declaration,
+  DeclarationProps,
+} from "./Declaration.js";
+import { PythonBlock } from "./PythonBlock.jsx";
+
+export interface ClassDeclarationProps extends BaseDeclarationProps {
+  /**
+   * The base classes that this class inherits from.
+   */
+  bases?: Children[];
+}
+
+/**
+ * Create a Python class declaration.
+ *
+ * @example
+ * ```tsx
+ * <ClassDeclaration name="MyClass" bases={["BaseClass"]}>
+ *   <VariableDeclaration name="a" type="int" />
+ *   <VariableDeclaration name="b" type="str" />
+ *   <py.FunctionDeclaration name="my_method" parameters={[{ name: "a", type: "int" }, { name: "b", type: "str" }]} returnType="int">
+ *     return a + b
+ *   </py.FunctionDeclaration>
+ * </ClassDeclaration>
+ * ```
+ * renders to
+ * ```py
+ * class MyClass(BaseClass):
+ *   a: int = None
+ *   b: str = None
+ *   def my_method(self, a: int, b: str) -> int:
+ *     return a + b
+ * ```
+ * @remarks
+ *
+ * Any child declarations (methods, fields, nested classes) will be placed
+ * in the class scope. This component creates a class scope to hold its
+ * members.
+ */
+export function ClassDeclaration(props: ClassDeclarationProps) {
+  const basesPart = props.bases && (
+    <>
+      (<List children={props.bases} comma space />)
+    </>
+  );
+
+  const sym = createPythonSymbol(
+    props.name!,
+    {
+      refkeys: props.refkey,
+      flags:
+        (props.flags ?? OutputSymbolFlags.None) |
+        OutputSymbolFlags.MemberContainer,
+    },
+    "class",
+    true,
+  );
+
+  takeSymbols((memberSymbol) => {
+    // Transform emitted symbols into instance/class members
+    memberSymbol.flags |= OutputSymbolFlags.InstanceMember;
+  });
+
+  // Propagate the name after the name policy was applied
+  const updatedProps: DeclarationProps = {
+    ...props,
+    name: sym.name,
+    nameKind: "class",
+  };
+  const hasChildren =
+    childrenArray(() => props.children).filter((c) => Boolean(c)).length > 0;
+
+  return (
+    <Declaration symbol={sym}>
+      class <Name />
+      <Scope name={updatedProps.name} kind="class">
+        {basesPart}
+        <PythonBlock opener=":">
+          <Show when={Boolean(props.doc)}>{props.doc}</Show>
+          {hasChildren ? props.children : "pass"}
+        </PythonBlock>
+      </Scope>
+    </Declaration>
+  );
+}

package/src/components/ClassInstantiation.tsx

@@ -0,0 +1,54 @@
+import {
+  emitSymbol,
+  instantiateTakenMembersTo as instantiateTakenSymbolsTo,
+  OutputSymbolFlags,
+  useContext,
+} from "@alloy-js/core";
+import { createPythonSymbol } from "../symbol-creation.js";
+import {
+  FunctionCallExpression,
+  FunctionCallExpressionProps,
+} from "./FunctionCallExpression.jsx";
+import { PythonSourceFileContext } from "./SourceFile.jsx";
+
+export interface ClassInstantiationProps extends FunctionCallExpressionProps {}
+
+/**
+ * Used to create new instances of classes in Python.
+ *
+ * @example
+ * ```tsx
+ * <ClassInstantiation target="MyClass" args={["arg1", "arg2"]} />
+ * ```
+ * This will generate:
+ * ```python
+ * MyClass(arg1, arg2)
+ * ```
+ * @remarks
+ *
+ * It is similar to FunctionCallExpression but specifically for class instantiation.
+ * Args should be a list arguments that can be either simple js values or py.Atoms, which will render as positional arguments,
+ * or py.VariableDeclarations, which will render as named arguments in the call statement. This component will
+ * not check for the correctness of the python grammar and will just work with any children you provide.
+ * It is up to you to ensure that the arguments you provide are valid in the context of a class instantiation.
+ */
+export function ClassInstantiation(props: ClassInstantiationProps) {
+  const sfContext = useContext(PythonSourceFileContext);
+  const module = sfContext?.module;
+  const sym = createPythonSymbol(
+    "",
+    {
+      flags: OutputSymbolFlags.Transient,
+      module: module,
+    },
+    undefined,
+    false,
+  );
+  instantiateTakenSymbolsTo(sym);
+  emitSymbol(sym);
+  return (
+    <>
+      <FunctionCallExpression {...props} />
+    </>
+  );
+}

package/src/components/Declaration.tsx

@@ -0,0 +1,91 @@
+import {
+  Children,
+  Declaration as CoreDeclaration,
+  MemberScope,
+  OutputSymbolFlags,
+  Refkey,
+} from "@alloy-js/core";
+import { PythonElements } from "../name-policy.js";
+import { createPythonSymbol } from "../symbol-creation.js";
+import { PythonOutputSymbol } from "../symbols/index.js";
+
+export interface BaseDeclarationProps {
+  /**
+   * The base name of this declaration. May change depending on naming policy
+   * and any conflicts.
+   */
+  name: string;
+
+  /**
+   * The refkey or array of refkeys for this declaration.
+   */
+  refkey?: Refkey | Refkey[];
+
+  /**
+   * Flags for the symbol created by this component.
+   */
+  flags?: OutputSymbolFlags;
+
+  children?: Children;
+
+  /**
+   * Documentation for this declaration
+   */
+  doc?: Children;
+}
+
+export interface DeclarationProps extends Omit<BaseDeclarationProps, "name"> {
+  /**
+   * The name of this declaration.
+   */
+  name?: string;
+
+  /**
+   * The name policy kind to apply to the declaration.
+   */
+  nameKind?: PythonElements;
+
+  /**
+   * The symbol to use for this declaration.
+   */
+  symbol?: PythonOutputSymbol;
+}
+
+/**
+ * A Python declaration, which can be a class, function, variable, etc.
+ *
+ * @remarks
+ * This component is used to create a declaration with a symbol that can be
+ * referenced in the code. It can also be used to create a member scope for
+ * member containers.
+ *
+ */
+export function Declaration(props: DeclarationProps) {
+  let sym: PythonOutputSymbol;
+
+  if (props.symbol) {
+    sym = props.symbol;
+  } else {
+    sym = createPythonSymbol(
+      props.name!,
+      {
+        refkeys: props.refkey,
+        flags: props.flags,
+      },
+      props.nameKind!,
+      true,
+    );
+  }
+
+  function withMemberScope(children: Children) {
+    return <MemberScope owner={sym}>{children}</MemberScope>;
+  }
+
+  let children: Children = () => props.children;
+
+  if (sym.flags & OutputSymbolFlags.MemberContainer) {
+    children = withMemberScope(children);
+  }
+
+  return <CoreDeclaration symbol={sym}>{children}</CoreDeclaration>;
+}

package/src/components/EnumDeclaration.tsx

@@ -0,0 +1,291 @@
+import {
+  Children,
+  Declaration as CoreDeclaration,
+  For,
+  MemberScope,
+  OutputSymbolFlags,
+  Scope,
+  Show,
+  useBinder,
+} from "@alloy-js/core";
+import { enumModule } from "../builtins/python.js";
+import { createPythonSymbol } from "../symbol-creation.js";
+import { usePythonScope } from "../symbols/scopes.js";
+import { BaseDeclarationProps } from "./Declaration.js";
+import { EnumMember } from "./EnumMember.js";
+import { PythonBlock } from "./PythonBlock.jsx";
+import { SimpleCommentBlock } from "./index.js";
+
+export interface EnumProps extends BaseDeclarationProps {
+  /**
+   * The base type of the enum. One of: 'Enum', 'IntEnum', 'StrEnum', 'Flag', 'IntFlag'.
+   * Defaults to 'Enum'.
+   */
+  baseType?: "Enum" | "IntEnum" | "StrEnum" | "Flag" | "IntFlag";
+  /**
+   * Members of the enum as an array of objects.
+   */
+  members?: Array<{
+    name: string;
+    value?: Children;
+    jsValue?: string | number;
+    doc?: string;
+  }>;
+  /**
+   * 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} />;
+}
+
+/**
+ * Create a Python enum using the functional syntax.
+ *
+ * This generates enums using the `Enum('Name', [...])` or `Enum('Name', {...})` syntax.
+ * The format depends on whether enum members have explicit values:
+ * - Members without values: `Enum('Direction', ['NORTH', 'SOUTH', 'EAST', 'WEST'])`
+ * - Members with values: `Enum('Direction', {'NORTH': 1, 'SOUTH': 2, 'EAST': 3, 'WEST': 4})`
+ *
+ * @example
+ * ```tsx
+ * <FunctionalEnumDeclaration
+ *   name="Direction"
+ *   members={[
+ *     { name: "NORTH" },
+ *     { name: "SOUTH" },
+ *     { name: "EAST" },
+ *     { name: "WEST" }
+ *   ]}
+ * />
+ * ```
+ * renders to:
+ * ```python
+ * Direction = Enum('Direction', ['NORTH', 'SOUTH', 'EAST', 'WEST'])
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <FunctionalEnumDeclaration
+ *   name="Status"
+ *   members={[
+ *     { name: "PENDING", value: 1 },
+ *     { name: "ACTIVE", value: 2 },
+ *     { name: "INACTIVE", value: 3 }
+ *   ]}
+ * />
+ * ```
+ * renders to:
+ * ```python
+ * Status = Enum('Status', {'PENDING': 1, 'ACTIVE': 2, 'INACTIVE': 3})
+ * ```
+ */
+export function FunctionalEnumDeclaration(props: EnumProps) {
+  const binder = useBinder();
+  const scope = usePythonScope();
+  const sym = createPythonSymbol(
+    props.name,
+    {
+      binder: binder,
+      scope: scope,
+      refkeys: props.refkey,
+      flags: OutputSymbolFlags.StaticMemberContainer,
+    },
+    "enum",
+    false,
+  );
+  const members = props.members ?? [];
+  let opener, ender;
+  if (members.length && members.every((m) => m.value === undefined)) {
+    // List of names: Enum('Direction', ['NORTH', ...])
+    opener = "[";
+    ender = "]";
+  } else {
+    // List of name-value pairs: Enum('Direction', {'NORTH': 1, ...})
+    opener = "{";
+    ender = "}";
+  }
+  const memberExpr = (
+    <>
+      {opener}
+      <For each={members} joiner=", ">
+        {(m) => <EnumMember name={m.name} value={m.value} functional={true} />}
+      </For>
+      {ender}
+    </>
+  );
+  return (
+    <>
+      <CoreDeclaration symbol={sym}>
+        {sym.name} = {enumModule["."].Enum}('{sym.name}',{" "}
+        <MemberScope owner={sym}>
+          <Scope name={props.name} kind="enum">
+            {memberExpr}
+          </Scope>
+        </MemberScope>
+        )
+      </CoreDeclaration>
+    </>
+  );
+}
+
+/**
+ * Create a Python enum using the class-based syntax.
+ *
+ * This generates enums using the `class Name(Enum):` syntax with member definitions
+ * inside the class body. Supports various member value styles including auto-generated
+ * values, explicit values, and custom base types.
+ *
+ * @example
+ * ```tsx
+ * <ClassEnumDeclaration
+ *   name="Direction"
+ *   members={[
+ *     { name: "NORTH" },
+ *     { name: "SOUTH" },
+ *     { name: "EAST" },
+ *     { name: "WEST" }
+ *   ]}
+ * />
+ * ```
+ * renders to:
+ * ```python
+ * class Direction(Enum):
+ *     NORTH = "NORTH"
+ *     SOUTH = "SOUTH"
+ *     EAST = "EAST"
+ *     WEST = "WEST"
+ * ```
+ *
+ * @example
+ * With explicit values:
+ * ```tsx
+ * <ClassEnumDeclaration
+ *   name="Status"
+ *   members={[
+ *     { name: "PENDING", value: 1 },
+ *     { name: "ACTIVE", value: 2 },
+ *     { name: "INACTIVE", value: 3 }
+ *   ]}
+ * />
+ * ```
+ * renders to:
+ * ```python
+ * class Status(Enum):
+ *     PENDING = 1
+ *     ACTIVE = 2
+ *     INACTIVE = 3
+ * ```
+ *
+ * @example
+ * With auto() values:
+ * ```tsx
+ * <ClassEnumDeclaration
+ *   name="Color"
+ *   style="auto"
+ *   members={[
+ *     { name: "RED" },
+ *     { name: "GREEN" },
+ *     { name: "BLUE" }
+ *   ]}
+ * />
+ * ```
+ * renders to:
+ * ```python
+ * class Color(Enum):
+ *     RED = auto()
+ *     GREEN = auto()
+ *     BLUE = auto()
+ * ```
+ */
+export function ClassEnumDeclaration(props: EnumProps) {
+  const baseType = props.baseType || "Enum";
+  const binder = useBinder();
+  const scope = usePythonScope();
+  const sym = createPythonSymbol(
+    props.name,
+    {
+      binder: binder,
+      scope: scope,
+      refkeys: props.refkey,
+      flags: OutputSymbolFlags.StaticMemberContainer,
+    },
+    "enum",
+    false,
+  );
+  let memberList: Array<{
+    name: string;
+    value?: Children;
+    jsValue?: string | number;
+    auto?: boolean;
+    doc?: string;
+  }> = (props.members ?? []).map((m) =>
+    m.value === undefined ? { ...m, auto: false } : m,
+  );
+  if (props.style === "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 owner={sym}>
+        <Scope name={sym.name} kind="enum">
+          <PythonBlock opener=":">
+            <For each={memberList} hardline>
+              {(member) => (
+                <EnumMember
+                  name={member.name}
+                  value={member.value}
+                  jsValue={member.jsValue}
+                  auto={member.auto}
+                  doc={member.doc}
+                />
+              )}
+            </For>
+            {props.children}
+          </PythonBlock>
+        </Scope>
+      </MemberScope>
+    </CoreDeclaration>
+  );
+}

package/src/components/EnumMember.tsx

@@ -0,0 +1,92 @@
+import { Children, OutputSymbolFlags, Refkey, Show } from "@alloy-js/core";
+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";
+
+export interface EnumMemberProps {
+  /**
+   * The name of the enum member.
+   */
+  name: string;
+
+  /**
+   * Refkey for the enum member symbol. If the refkey is not provided, a symbol
+   * will be created and the member cannot be referenced by refkey.
+   */
+  refkey?: Refkey;
+
+  /**
+   * The value of the enum member.
+   */
+  value?: Children;
+
+  /**
+   * The JS value of the enum member.
+   */
+  jsValue?: string | number;
+
+  /**
+   * Functional mappings/list
+   */
+  functional?: boolean;
+
+  /**
+   * Will use auto() to generate the value if set to true.
+   */
+  auto?: boolean;
+
+  /**
+   * Documentation for the enum member.
+   */
+  doc?: Children;
+}
+
+/**
+ * A Python enum member.
+ *
+ * @example
+ * ```tsx
+ * <EnumMember name="NORTH" />
+ * ```
+ * This will generate:
+ * ```python
+ * NORTH
+ * ```
+ */
+export function EnumMember(props: EnumMemberProps) {
+  const autoReference = props.auto === true ? enumModule["."].auto : undefined;
+  const value = props.auto === true ? <>{autoReference}()</> : props.value;
+  const sym: PythonOutputSymbol = createPythonSymbol(
+    props.name,
+    {
+      refkeys: props.refkey,
+      flags: OutputSymbolFlags.StaticMember,
+    },
+    "enum-member",
+    true,
+  );
+  const valueCode =
+    props.jsValue !== undefined ? <Atom jsValue={props.jsValue} /> : value;
+
+  if (props.functional) {
+    return (
+      <>
+        '{sym.name}'<Show when={valueCode !== undefined}> : {valueCode}</Show>
+        <Show when={props.doc !== undefined}>
+          <SimpleInlineComment>{props.doc}</SimpleInlineComment>
+        </Show>
+      </>
+    );
+  }
+  return (
+    <>
+      {sym.name}
+      <Show when={valueCode !== undefined}> = {valueCode}</Show>
+      <Show when={props.doc !== undefined}>
+        <SimpleInlineComment>{props.doc}</SimpleInlineComment>
+      </Show>
+    </>
+  );
+}

package/src/components/FunctionCallExpression.tsx

@@ -0,0 +1,36 @@
+import { Children, For, Indent, Wrap } from "@alloy-js/core";
+
+export interface FunctionCallExpressionProps {
+  target: Children;
+  args?: Children[];
+}
+
+/**
+ * A Python function call expression.
+ *
+ * @example
+ * ```tsx
+ * <FunctionCallExpression target="foo" args={["arg1", "arg2"]} />
+ * ```
+ * This will generate:
+ * ```python
+ * foo(arg1, arg2)
+ * ```
+ */
+export function FunctionCallExpression(props: FunctionCallExpressionProps) {
+  return (
+    <group>
+      {props.target}(
+      <Wrap
+        when={!!props.args && props.args.length > 1}
+        with={Indent}
+        props={{ softline: true, trailingBreak: true }}
+      >
+        <For each={props.args ?? []} comma line>
+          {(arg) => arg}
+        </For>
+      </Wrap>
+      )
+    </group>
+  );
+}