Execute changes in the Python implementation (alloy-framework#302)

## Create `SingleTypeExpression`
Create `TypeReference ` to handle some edge cases on typing (involving
typeArgs) to, in addition to the already present `UnionTypeExpression`,
more properly represent the typing in Python.

## Refactor `FunctionDeclaration`
Refactor FunctionDeclaration to more properly represent each scenario:

- FunctionDeclaration: Standalone function. Has the functionType
parameter.
- MethodDeclaration: Normal method
- ClassMethodDeclaration: Class method, prepended with @classmethod
- StaticMethodDeclaration: Static method, prepended with @staticmethod
- DunderMethodDeclaration: Any dunder method. Any formatting to the name
that would normally happen will be skipped
- ConstructorDeclaration: Special component for the __new__ dunder
method, which has cls as its first argument, but isn't decorated with
@classmethod
- PropertyDeclaration: Python properties, with setter and deleter
support, prepended with @Property

Also:
- Added abc module to be able to import @staticmethod
- Modified createPythonSymbol so it supports a reuseExisting, which
looks for existing symbol instead of creating a new one. Intended to
handle the @Property special cases

## Split Enum implementations
Split Enum implementations into FunctionalEnumDeclaration and
ClassEnumDeclaration.

## Split docs components into separate components
Make docs components more granular by splitting them into:
- ClassDoc
- FunctionDoc
- MethodDoc
- ModuleDoc
- PropertyDoc
- GeneratorDoc
- ExceptionDoc
- AttributeDoc

These are the only components that are meant to be used directly, and
are the only ones that are exported.

Also added the equivalent GoogleStyle-prefixed classes, bringing the
Google-style implementation of these.

---------

Co-authored-by: Steve Rice <srice@pinterest.com>

Author: mauriciogardini

.chronus/changes/feature-python-refactors-2025-8-16-20-39-55.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@alloy-js/python"
+---
+
+Create SingleTypeExpression, refactor FunctionDeclaration, split Enum implementations and split docs components into separate components

packages/python/src/builtins/python.ts

@@ -4,6 +4,13 @@ import { createModule } from "../create-module.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 type dummy = SymbolCreator;
 
+export const abcModule = createModule({
+  name: "abc",
+  descriptor: {
+    ".": ["abstractmethod"],
+  },
+});
+
 export const enumModule = createModule({
   name: "enum",
   descriptor: {

packages/python/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 =

packages/python/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} />
+    </>
+  );
+}

packages/python/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}
+    />
+  );
+}

packages/python/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} />;
+}

packages/python/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