@typespec/emitter-framework 0.15.0-dev.3 → 0.15.0

package/src/python/components/class-declaration/class-method.tsx

@@ -0,0 +1,97 @@
+import { type Children, createContext, splitProps, useContext } from "@alloy-js/core";
+import * as py from "@alloy-js/python";
+import type { Operation } from "@typespec/compiler";
+import { useTsp } from "../../../core/index.js";
+import { buildParameterDescriptors, getReturnType } from "../../utils/operation.js";
+import { DocElement } from "../doc-element/doc-element.js";
+import { TypeExpression } from "../type-expression/type-expression.js";
+
+export const MethodContext = createContext<"method" | "static" | "class" | undefined>(undefined);
+export const MethodProvider = MethodContext.Provider;
+
+export interface MethodPropsWithType extends Omit<py.MethodDeclarationBaseProps, "name"> {
+  type: Operation;
+  name?: string;
+  doc?: Children;
+  methodType?: "method" | "class" | "static";
+  abstract?: boolean;
+  /** If true, parameters replaces operation parameters instead of adding to them as keyword-only */
+  replaceParameters?: boolean;
+}
+
+export type MethodProps = MethodPropsWithType | py.MethodDeclarationBaseProps;
+
+/**
+ * Get the method component based on the resolved method type.
+ * We prioritize the methodType prop provided in the Method component,
+ * and then the one provided in the context, and then we default to "method".
+ */
+function getResolvedMethodType(props: MethodProps): "method" | "class" | "static" {
+  const ctxMethodType = useContext(MethodContext);
+  const propMethodType = "methodType" in props ? (props as any).methodType : undefined;
+  return (propMethodType ?? ctxMethodType ?? "method") as "method" | "class" | "static";
+}
+
+/**
+ * A Python class method. Pass the `type` prop to create the
+ * method by converting from a TypeSpec Operation. Any other props
+ * provided will take precedence.
+ */
+export function Method(props: Readonly<MethodProps>) {
+  const { $ } = useTsp();
+  const isTypeSpecTyped = "type" in props;
+  const type = isTypeSpecTyped ? props.type : undefined;
+  const docSource = props.doc ?? (type ? $.type.getDoc(type) : undefined);
+  const docElement = docSource ? (
+    <DocElement doc={docSource} component={py.MethodDoc} />
+  ) : undefined;
+  const resolvedMethodType = getResolvedMethodType(props);
+  const MethodComponent =
+    resolvedMethodType === "static"
+      ? py.StaticMethodDeclaration
+      : resolvedMethodType === "class"
+        ? py.ClassMethodDeclaration
+        : py.MethodDeclaration;
+
+  // Default to abstract when deriving from a TypeSpec operation (`type` prop present),
+  // unless explicitly overridden by props.abstract === false
+  const abstractFlag = (() => {
+    const explicit = (props as any).abstract as boolean | undefined;
+    return explicit ?? (!isTypeSpecTyped ? false : undefined);
+  })();
+
+  /**
+   * If the method does not come from the Typespec class declaration, return a standard Python method declaration.
+   * Have in mind that, with that, we lose some of the TypeSpec class declaration overrides.
+   */
+  if (!isTypeSpecTyped) {
+    return <MethodComponent {...props} doc={docElement} abstract={abstractFlag} />;
+  }
+
+  const [efProps, updateProps, forwardProps] = splitProps(
+    props,
+    ["type"],
+    ["returnType", "parameters"],
+  );
+
+  const name = props.name ?? py.usePythonNamePolicy().getName(efProps.type.name, "function");
+  const returnType = props.returnType ?? <TypeExpression type={getReturnType(efProps.type)} />;
+  const allParameters = buildParameterDescriptors(efProps.type.parameters, {
+    params: props.parameters,
+    replaceParameters: props.replaceParameters,
+  });
+
+  return (
+    <>
+      <MethodComponent
+        {...forwardProps}
+        {...updateProps}
+        name={name}
+        returnType={returnType}
+        parameters={allParameters}
+        doc={docElement}
+        abstract={abstractFlag}
+      />
+    </>
+  );
+}

package/src/python/components/class-declaration/index.ts

@@ -0,0 +1,6 @@
+export * from "./class-bases.js";
+export * from "./class-body.js";
+export * from "./class-declaration.js";
+export * from "./class-member.js";
+export * from "./class-method.js";
+export * from "./primitive-initializer.js";

package/src/python/components/class-declaration/primitive-initializer.tsx

@@ -0,0 +1,62 @@
+import { type Children } from "@alloy-js/core";
+import * as py from "@alloy-js/python";
+import type { Type, Value } from "@typespec/compiler";
+import { useTsp } from "../../../core/context/tsp-context.js";
+import { Atom } from "../atom/atom.js";
+
+export interface PrimitiveInitializerProps {
+  /**
+   * The default value to convert to a Python initializer expression.
+   */
+  defaultValue: Value;
+  /**
+   * The property type, used to determine float vs int formatting.
+   */
+  propertyType: Type;
+}
+
+/**
+ * Renders a Python primitive initializer from a TypeSpec default value.
+ *
+ * Handles StringValue, BooleanValue, NullValue, NumericValue, and ArrayValue.
+ * For numeric values, uses the propertyType to determine whether to render as float.
+ *
+ * @returns The Python initializer expression, or undefined if not supported.
+ */
+export function PrimitiveInitializer(props: PrimitiveInitializerProps): Children | undefined {
+  const { $ } = useTsp();
+  const { defaultValue, propertyType } = props;
+
+  if (!defaultValue) return undefined;
+
+  const valueKind = (defaultValue as any).valueKind ?? (defaultValue as any).kind;
+  switch (valueKind) {
+    case "StringValue":
+    case "BooleanValue":
+    case "NullValue":
+      return <py.Atom jsValue={(defaultValue as any).value} />;
+    case "NumericValue": {
+      // The Atom component converts NumericValue via asNumber(), which normalizes 100.0 to 100.
+      // Atom also has no access to the field type (float vs int), so it can't decide when to keep a trailing .0.
+      // Here we do have the propertyType so, for float/decimal fields, we render a raw value and append ".0"
+      // when needed. For non-float fields, default to a plain numeric Atom.
+
+      // Unwrap potential numeric wrapper shape and preserve float formatting
+      let raw: any = (defaultValue as any).value;
+      // Example: value is { value: "100", isInteger: true }
+      if (raw && typeof raw === "object" && "value" in raw) raw = raw.value;
+
+      // Float-like property types (including custom subtypes) should render with float hint
+      if ($.scalar.extendsFloat(propertyType) || $.scalar.extendsDecimal(propertyType)) {
+        return <Atom value={defaultValue} float />;
+      }
+
+      // Otherwise output as a number atom
+      return <py.Atom jsValue={Number(raw)} />;
+    }
+    case "ArrayValue":
+      return <Atom value={defaultValue} />;
+    default:
+      return undefined;
+  }
+}

package/src/python/components/doc-element/doc-element.tsx

@@ -0,0 +1,83 @@
+import { type Children, type Component, List } from "@alloy-js/core";
+import type { Type } from "@typespec/compiler";
+import { useTsp } from "../../../core/context/tsp-context.js";
+
+export interface DocElementProps {
+  /**
+   * The TypeSpec type to get documentation from.
+   * If provided and no `doc` override is given, documentation will be
+   * fetched via `$.type.getDoc(type)`.
+   */
+  type?: Type;
+
+  /**
+   * Optional documentation override. If provided, this takes precedence
+   * over documentation from the `type` prop.
+   *
+   * Accepts:
+   * - string - split into lines and render as a multi-line docstring
+   * - string[] | Children[] - rendered as separate paragraphs
+   * - Children (e.g., an explicit Doc component) - returned as-is
+   */
+  doc?: string | string[] | Children | Children[];
+
+  /**
+   * The Python doc component to use for rendering (ClassDoc, FunctionDoc, MethodDoc, etc.)
+   */
+  component: Component<{ description: Children[] }>;
+}
+
+/**
+ * Renders documentation for a Python declaration.
+ *
+ * This component handles fetching documentation from TypeSpec types and
+ * normalizing various doc formats into the appropriate Python doc component.
+ *
+ * @example
+ * ```tsx
+ * // With a TypeSpec type (fetches doc automatically)
+ * <DocElement type={model} component={py.ClassDoc} />
+ *
+ * // With an explicit doc override
+ * <DocElement doc="My custom documentation" component={py.FunctionDoc} />
+ *
+ * // With both (doc takes precedence)
+ * <DocElement type={model} doc={props.doc} component={py.ClassDoc} />
+ * ```
+ */
+export function DocElement(props: DocElementProps): Children {
+  const { $ } = useTsp();
+
+  // Resolve the documentation source: explicit doc takes precedence over type-derived doc
+  const source = props.doc ?? (props.type ? $.type.getDoc(props.type) : undefined);
+
+  if (!source) {
+    return undefined;
+  }
+
+  const DocComponent = props.component;
+
+  // Doc provided as an array (paragraphs/nodes) - preserve structure
+  if (Array.isArray(source)) {
+    return <DocComponent description={source as Children[]} />;
+  }
+
+  // Doc provided as a string - preserve line breaks
+  if (typeof source === "string") {
+    const lines = source.split(/\r?\n/);
+    return (
+      <DocComponent
+        description={[
+          <List hardline>
+            {lines.map((line) => (
+              <>{line}</>
+            ))}
+          </List>,
+        ]}
+      />
+    );
+  }
+
+  // Doc provided as JSX - pass through unchanged
+  return source as Children;
+}

package/src/python/components/doc-element/index.ts

@@ -0,0 +1 @@
+export * from "./doc-element.js";

package/src/python/components/enum-declaration/enum-declaration.test.tsx

@@ -0,0 +1,319 @@
+import { efRefkey } from "#python/utils/refkey.js";
+import { Tester } from "#test/test-host.js";
+import { d } from "@alloy-js/core/testing";
+import * as py from "@alloy-js/python";
+import { t } from "@typespec/compiler/testing";
+import { describe, expect, it } from "vitest";
+import { getOutput } from "../../test-utils.js";
+import { EnumDeclaration } from "./enum-declaration.js";
+
+describe("Python Enum Declaration", () => {
+  it("takes an enum type parameter", async () => {
+    const { program, Foo } = await Tester.compile(t.code`
+      enum ${t.enum("Foo")} {
+        one: 1,
+        two: 2,
+        three: 3
+      }
+    `);
+
+    expect(getOutput(program, [<EnumDeclaration type={Foo} />])).toRenderTo(d`
+      from enum import IntEnum
+
+
+      class Foo(IntEnum):
+        ONE = 1
+        TWO = 2
+        THREE = 3
+
+
+    `);
+  });
+
+  it("adds Python doc from TypeSpec", async () => {
+    const { program, Foo } = await Tester.compile(t.code`
+      /**
+       * This is a test enum
+       */
+      enum ${t.enum("Foo")} {
+        @doc("This is one")
+        one: 1,
+        two: 2,
+        three: 3
+      }
+    `);
+    const output = getOutput(program, [<EnumDeclaration type={Foo} />]);
+
+    expect(output).toRenderTo(d`
+      from enum import IntEnum
+
+
+      class Foo(IntEnum):
+        """
+        This is a test enum
+        """
+
+        ONE = 1
+        """
+        This is one
+        """
+        TWO = 2
+        THREE = 3
+
+
+    `);
+  });
+
+  it("explicit doc take precedence", async () => {
+    const { program, Foo } = await Tester.compile(t.code`
+      /**
+       * This is a test enum
+       */
+      enum ${t.enum("Foo")} {
+        @doc("This is one")
+        one: 1,
+        two: 2,
+        three: 3
+      }
+    `);
+    const output = getOutput(program, [
+      <EnumDeclaration type={Foo} doc={["This is an explicit doc"]} />,
+    ]);
+
+    expect(output).toRenderTo(d`
+      from enum import IntEnum
+
+
+      class Foo(IntEnum):
+        """
+        This is an explicit doc
+        """
+
+        ONE = 1
+        """
+        This is one
+        """
+        TWO = 2
+        THREE = 3
+
+
+    `);
+  });
+
+  it("takes a union type parameter", async () => {
+    const { program, Foo } = await Tester.compile(t.code`
+      union ${t.union("Foo")} {
+        one: 1,
+        two: 2,
+        three: 3
+      }
+    `);
+    const output = getOutput(program, [<EnumDeclaration type={Foo} />]);
+
+    expect(output).toRenderTo(d`
+      from enum import IntEnum
+
+
+      class Foo(IntEnum):
+        ONE = 1
+        TWO = 2
+        THREE = 3
+
+
+    `);
+  });
+
+  it("can be referenced", async () => {
+    const { program, Foo } = await Tester.compile(t.code`
+      enum ${t.enum("Foo")} {
+        one: 1,
+        two: 2,
+        three: 3
+      }
+    `);
+
+    const output = getOutput(program, [
+      <EnumDeclaration type={Foo} />,
+      <py.StatementList>
+        {efRefkey(Foo)}
+        {efRefkey(Foo.members.get("one"))}
+      </py.StatementList>,
+    ]);
+
+    expect(output).toRenderTo(d`
+      from enum import IntEnum
+
+
+      class Foo(IntEnum):
+        ONE = 1
+        TWO = 2
+        THREE = 3
+
+
+      Foo
+      Foo.ONE
+    `);
+  });
+
+  it("can be referenced using union", async () => {
+    const { program, Foo } = await Tester.compile(t.code`
+      union ${t.union("Foo")}  {
+        one: 1,
+        two: 2,
+        three: 3
+      }
+    `);
+
+    const output = getOutput(program, [
+      <EnumDeclaration type={Foo} />,
+      <py.StatementList>
+        {efRefkey(Foo)}
+        {efRefkey(Foo.variants.get("one"))}
+      </py.StatementList>,
+    ]);
+
+    expect(output).toRenderTo(d`
+      from enum import IntEnum
+
+
+      class Foo(IntEnum):
+        ONE = 1
+        TWO = 2
+        THREE = 3
+
+
+      Foo
+      Foo.ONE
+    `);
+  });
+
+  describe("Enum Type Detection", () => {
+    it("generates IntEnum if all values are integer values", async () => {
+      const { program, StatusCode } = await Tester.compile(t.code`
+        enum ${t.enum("StatusCode")} {
+          success: 200,
+          notFound: 404,
+          serverError: 500
+        }
+      `);
+      const output = getOutput(program, [<EnumDeclaration type={StatusCode} />]);
+
+      expect(output).toRenderTo(d`
+        from enum import IntEnum
+
+
+        class StatusCode(IntEnum):
+          SUCCESS = 200
+          NOT_FOUND = 404
+          SERVER_ERROR = 500
+
+
+      `);
+    });
+
+    it("generates StrEnum if all values are string values", async () => {
+      const { program, Color } = await Tester.compile(t.code`
+        enum ${t.enum("Color")} {
+          red: "red",
+          green: "green",
+          blue: "blue"
+        }
+      `);
+      const output = getOutput(program, [<EnumDeclaration type={Color} />]);
+
+      expect(output).toRenderTo(d`
+        from enum import StrEnum
+
+
+        class Color(StrEnum):
+          RED = "red"
+          GREEN = "green"
+          BLUE = "blue"
+
+
+      `);
+    });
+
+    it("generates StrEnum if all values are string values with custom values", async () => {
+      const { program, Color } = await Tester.compile(t.code`
+        enum ${t.enum("Color")} {
+          red: "This is red",
+          green: "This is green",
+          blue: "This is blue"
+        }
+      `);
+      const output = getOutput(program, [
+        <EnumDeclaration type={Color} />,
+        <py.StatementList>
+          {efRefkey(Color.members.get("red"))}
+          {efRefkey(Color.members.get("green"))}
+          {efRefkey(Color.members.get("blue"))}
+        </py.StatementList>,
+      ]);
+
+      expect(output).toRenderTo(d`
+        from enum import StrEnum
+
+
+        class Color(StrEnum):
+          RED = "This is red"
+          GREEN = "This is green"
+          BLUE = "This is blue"
+
+
+        Color.RED
+        Color.GREEN
+        Color.BLUE
+
+      `);
+    });
+
+    it("generates Enum for mixed value types", async () => {
+      const { program, Mixed } = await Tester.compile(t.code`
+        enum ${t.enum("Mixed")} {
+          stringValue: "hello",
+          numericValue: 42,
+          autoValue
+        }
+      `);
+      const output = getOutput(program, [<EnumDeclaration type={Mixed} />]);
+
+      expect(output).toRenderTo(d`
+        from enum import auto
+        from enum import Enum
+
+
+        class Mixed(Enum):
+          STRING_VALUE = "hello"
+          NUMERIC_VALUE = 42
+          AUTO_VALUE = auto()
+        
+        
+      `);
+    });
+
+    it("handles correctly enums without values", async () => {
+      const { program, EnumWithoutValues } = await Tester.compile(t.code`
+        enum ${t.enum("EnumWithoutValues")} {
+          someValue,
+          anotherValue,
+          yetAnotherValue
+        }
+      `);
+      const output = getOutput(program, [<EnumDeclaration type={EnumWithoutValues} />]);
+
+      expect(output).toRenderTo(d`
+        from enum import auto
+        from enum import Enum
+
+
+        class EnumWithoutValues(Enum):
+          SOME_VALUE = auto()
+          ANOTHER_VALUE = auto()
+          YET_ANOTHER_VALUE = auto()
+        
+        
+      `);
+    });
+  });
+});

package/src/python/components/enum-declaration/enum-declaration.tsx

@@ -0,0 +1,77 @@
+import { useTsp } from "#core/context/index.js";
+import { For, Prose } from "@alloy-js/core";
+import * as py from "@alloy-js/python";
+import type { Enum, EnumMember as TspEnumMember, Union } from "@typespec/compiler";
+import { reportDiagnostic } from "../../../lib.js";
+import { declarationRefkeys, efRefkey } from "../../utils/refkey.js";
+import { EnumMember } from "./enum-member.js";
+
+export interface EnumDeclarationProps extends Omit<py.BaseDeclarationProps, "name"> {
+  name?: string;
+  type: Union | Enum;
+}
+
+// Determine the appropriate enum type based on the member values
+function determineEnumType(
+  members: Array<[string, TspEnumMember]>,
+): "IntEnum" | "StrEnum" | "Enum" {
+  const allInteger = members.every(([, member]) => {
+    const value = member.value;
+    return typeof value === "number" && Number.isInteger(value);
+  });
+
+  const allString = members.every(([, member]) => {
+    const value = member.value;
+    return typeof value === "string";
+  });
+
+  if (allInteger) {
+    return "IntEnum";
+  } else if (allString) {
+    return "StrEnum";
+  } else {
+    return "Enum";
+  }
+}
+
+export function EnumDeclaration(props: EnumDeclarationProps) {
+  const { $ } = useTsp();
+  let type: Enum;
+  if ($.union.is(props.type)) {
+    if (!$.union.isValidEnum(props.type)) {
+      throw new Error("The provided union type cannot be represented as an enum");
+    }
+    type = $.enum.createFromUnion(props.type);
+  } else {
+    type = props.type;
+  }
+
+  if (!props.type.name) {
+    reportDiagnostic($.program, { code: "type-declaration-missing-name", target: props.type });
+  }
+  const refkeys = declarationRefkeys(props.refkey, props.type);
+  const name = props.name ?? py.usePythonNamePolicy().getName(props.type.name!, "enum");
+  const members = Array.from(type.members.entries());
+  const doc = props.doc ?? $.type.getDoc(type);
+  const docElement = doc ? <py.ClassDoc description={[<Prose>{doc}</Prose>]} /> : undefined;
+  const enumType = determineEnumType(members);
+
+  return (
+    <py.ClassEnumDeclaration doc={docElement} name={name} refkey={refkeys} baseType={enumType}>
+      <For each={members} hardline>
+        {([key, value]) => {
+          const memberDoc = $.type.getDoc(value);
+          return (
+            <EnumMember
+              doc={memberDoc}
+              type={value}
+              refkey={
+                $.union.is(props.type) ? efRefkey(props.type.variants.get(key)) : efRefkey(value)
+              }
+            />
+          );
+        }}
+      </For>
+    </py.ClassEnumDeclaration>
+  );
+}

package/src/python/components/enum-declaration/enum-member.tsx

@@ -0,0 +1,21 @@
+import { type Children, type Refkey } from "@alloy-js/core";
+import * as py from "@alloy-js/python";
+import type { EnumMember as TspEnumMember } from "@typespec/compiler";
+
+export interface EnumMemberProps {
+  type: TspEnumMember;
+  doc?: Children;
+  refkey?: Refkey;
+}
+
+export function EnumMember(props: EnumMemberProps) {
+  return (
+    <py.EnumMember
+      doc={props.doc}
+      name={props.type.name}
+      jsValue={props.type.value}
+      refkey={props.refkey}
+      auto={props.type.value === undefined}
+    />
+  );
+}

package/src/python/components/enum-declaration/index.ts

@@ -0,0 +1,2 @@
+export * from "./enum-declaration.js";
+export * from "./enum-member.js";