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

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

@@ -0,0 +1,116 @@
+import * as py from "@alloy-js/python";
+import { type Interface, type Model } from "@typespec/compiler";
+import { useTsp } from "../../../core/context/tsp-context.js";
+import { reportDiagnostic } from "../../../lib.js";
+import { declarationRefkeys } from "../../utils/refkey.js";
+import { DocElement } from "../doc-element/doc-element.js";
+import { ClassBases } from "./class-bases.js";
+import { ClassBody } from "./class-body.js";
+import { MethodProvider } from "./class-method.js";
+
+export interface ClassDeclarationPropsWithType extends Omit<py.ClassDeclarationProps, "name"> {
+  type: Model | Interface;
+  name?: string;
+  abstract?: boolean; // Global override for the abstract flag
+  methodType?: "method" | "class" | "static"; // Global override for the method type
+}
+
+export type ClassDeclarationProps = ClassDeclarationPropsWithType | py.ClassDeclarationProps;
+
+function isTypedClassDeclarationProps(
+  props: ClassDeclarationProps,
+): props is ClassDeclarationPropsWithType {
+  return "type" in props;
+}
+
+/**
+ * Converts TypeSpec Models and Interfaces to Python classes.
+ *
+ * - **Models** are converted into Dataclasses with `@dataclass(kw_only=True)` + fields
+ * - **Interfaces** are converted into Abstract classes (ABC) with abstract methods
+ * - For models that extends another model, we convert that into Python class inheritance
+ * - For interfaces that extends another interface, there's no inheritance, since
+ *   TypeSpec flattens the inheritance
+ *
+ * @param props - The props for the class declaration.
+ * @returns The class declaration.
+ */
+export function ClassDeclaration(props: ClassDeclarationProps) {
+  const { $ } = useTsp();
+
+  // Interfaces are rendered as abstract classes (ABC) with abstract methods
+  // Models are rendered as concrete dataclasses with fields
+  // If we are explicitly overriding the class as abstract or the type is not a model, we need to create an abstract class
+  const abstract =
+    ("abstract" in props && props.abstract) || ("type" in props && !$.model.is(props.type));
+
+  const type = "type" in props ? props.type : undefined;
+  const docSource = props.doc ?? (type ? $.type.getDoc(type) : undefined);
+  const docElement = docSource ? <DocElement doc={docSource} component={py.ClassDoc} /> : undefined;
+
+  // TODO: When TypeSpec adds true generics support, pass extraBases with Generic[T, ...] here.
+  // Currently, TypeSpec templates are macros that expand to concrete types, so we don't
+  // generate Python generics (TypeVar/Generic) for template declarations.
+  const basesType = ClassBases({
+    type: "type" in props ? props.type : undefined,
+    bases: props.bases,
+    abstract,
+  });
+
+  if (!isTypedClassDeclarationProps(props)) {
+    return (
+      <py.ClassDeclaration
+        {...props}
+        doc={docElement}
+        {...(basesType.length ? { bases: basesType } : {})}
+      />
+    );
+  }
+
+  const namePolicy = py.usePythonNamePolicy();
+
+  let name = props.name ?? props.type.name;
+  if (!name) {
+    reportDiagnostic($.program, { code: "type-declaration-missing-name", target: props.type });
+  }
+  name = namePolicy.getName(name, "class");
+
+  const refkeys = declarationRefkeys(props.refkey, props.type);
+
+  // Check for models with additional properties (Record-based scenarios)
+  // This check must happen here (in addition to ClassBody) because models with no properties
+  // (e.g., `model Foo is Record<string>`) won't render a ClassBody, so the error would never be thrown
+  if ($.model.is(props.type)) {
+    const additionalPropsRecord = $.model.getAdditionalPropertiesRecord(props.type);
+    if (additionalPropsRecord) {
+      throw new Error("Models with additional properties (Record[…]) are not supported");
+    }
+  }
+
+  // Array-based models (e.g., model Foo is Array<T>) use regular classes, not dataclasses,
+  // since Array models in TypeSpec can't have properties, so they behave more like a class
+  // that inherits from a list.
+  // Similarly, interfaces should use regular classes (ABC) not dataclasses, since interfaces
+  // only define abstract methods, not fields.
+  const isArrayModel = $.model.is(props.type) && $.array.is(props.type);
+  const isInterface = props.type.kind === "Interface";
+  const useDataclass = !isArrayModel && !isInterface;
+
+  const ClassComponent = useDataclass ? py.DataclassDeclaration : py.ClassDeclaration;
+
+  return (
+    <MethodProvider value={props.methodType}>
+      <ClassComponent
+        doc={docElement}
+        name={name}
+        {...(basesType.length ? { bases: basesType } : {})}
+        refkey={refkeys}
+        kwOnly={useDataclass ? true : undefined}
+      >
+        <ClassBody type={props.type} abstract={abstract} methodType={props.methodType}>
+          {props.children}
+        </ClassBody>
+      </ClassComponent>
+    </MethodProvider>
+  );
+}

package/src/python/components/class-declaration/class-member.test.tsx

@@ -0,0 +1,194 @@
+import { Tester } from "#test/test-host.js";
+import { t } from "@typespec/compiler/testing";
+import { describe, expect, it } from "vitest";
+import { ClassDeclaration } from "../../../../src/python/components/class-declaration/class-declaration.js";
+import { getOutput } from "../../test-utils.js";
+
+describe("Python Class Members", () => {
+  describe("default values", () => {
+    it("renders string default values", async () => {
+      const { program, MyModel } = await Tester.compile(t.code`
+      model ${t.model("MyModel")} {
+        name: string = "default";
+        description?: string = "optional with default";
+        emptyString: string = "";
+      }
+      `);
+
+      expect(getOutput(program, [<ClassDeclaration type={MyModel} />])).toRenderTo(
+        `
+          from dataclasses import dataclass
+          from typing import Optional
+
+
+          @dataclass(kw_only=True)
+          class MyModel:
+            name: str = "default"
+            description: Optional[str] = "optional with default"
+            empty_string: str = ""
+          
+          `,
+      );
+    });
+
+    it("renders boolean default values", async () => {
+      const { program, BooleanModel } = await Tester.compile(t.code`
+      model ${t.model("BooleanModel")} {
+        isActive: boolean = true;
+        isDeleted: boolean = false;
+        optional?: boolean = true;
+      }
+      `);
+
+      expect(getOutput(program, [<ClassDeclaration type={BooleanModel} />])).toRenderTo(
+        `
+          from dataclasses import dataclass
+          from typing import Optional
+
+
+          @dataclass(kw_only=True)
+          class BooleanModel:
+            is_active: bool = True
+            is_deleted: bool = False
+            optional: Optional[bool] = True
+          
+          `,
+      );
+    });
+
+    it("renders array default values", async () => {
+      const { program, ArrayModel } = await Tester.compile(t.code`
+      model ${t.model("ArrayModel")} {
+        tags: string[] = #["tag1", "tag2"];
+        emptyArray: int32[] = #[];
+        numbers: int32[] = #[1, 2, 3];
+      }
+      `);
+
+      expect(getOutput(program, [<ClassDeclaration type={ArrayModel} />])).toRenderTo(
+        `
+          from dataclasses import dataclass
+
+
+          @dataclass(kw_only=True)
+          class ArrayModel:
+            tags: list[str] = ["tag1", "tag2"]
+            empty_array: list[int] = []
+            numbers: list[int] = [1, 2, 3]
+          
+          `,
+      );
+    });
+
+    it("renders integer default values without .0 suffix", async () => {
+      const { program, IntegerModel } = await Tester.compile(t.code`
+      model ${t.model("IntegerModel")} {
+        count: int32 = 42;
+        bigNumber: int64 = 1000000;
+        smallNumber: int8 = 127;
+        unsignedValue: uint32 = 100;
+        safeIntValue: safeint = 999;
+      }
+      `);
+
+      expect(getOutput(program, [<ClassDeclaration type={IntegerModel} />])).toRenderTo(
+        `
+          from dataclasses import dataclass
+
+
+          @dataclass(kw_only=True)
+          class IntegerModel:
+            count: int = 42
+            big_number: int = 1000000
+            small_number: int = 127
+            unsigned_value: int = 100
+            safe_int_value: int = 999
+          
+          `,
+      );
+    });
+
+    it("renders float and decimal default values correctly", async () => {
+      const { program, NumericDefaults } = await Tester.compile(t.code`
+
+      scalar customFloat extends float;
+      scalar customDecimal extends decimal;
+
+      model ${t.model("NumericDefaults")} {
+        // Float variants with decimal values
+        floatBase: float = 1.5;
+        float32Value: float32 = 2.5;
+        float64Value: float64 = 3.5;
+        customFloatValue: customFloat = 4.5;
+        
+        // Float variants with integer values (should render with .0)
+        floatInt: float = 10;
+        float32Int: float32 = 20;
+        float64Int: float64 = 30;
+        
+        // Decimal variants
+        decimalBase: decimal = 100.25;
+        decimal128Value: decimal128 = 200.75;
+        customDecimalValue: customDecimal = 300.125;
+        
+        // Decimal with integer values (should render with .0)
+        decimalInt: decimal = 400;
+        decimal128Int: decimal128 = 500;
+      }
+      `);
+
+      expect(getOutput(program, [<ClassDeclaration type={NumericDefaults} />])).toRenderTo(
+        `
+          from dataclasses import dataclass
+          from decimal import Decimal
+
+
+          @dataclass(kw_only=True)
+          class NumericDefaults:
+            float_base: float = 1.5
+            float32_value: float = 2.5
+            float64_value: float = 3.5
+            custom_float_value: float = 4.5
+            float_int: float = 10.0
+            float32_int: float = 20.0
+            float64_int: float = 30.0
+            decimal_base: Decimal = 100.25
+            decimal128_value: Decimal = 200.75
+            custom_decimal_value: Decimal = 300.125
+            decimal_int: Decimal = 400.0
+            decimal128_int: Decimal = 500.0
+          
+          `,
+      );
+    });
+
+    it("distinguishes between integer and float types with same numeric value", async () => {
+      const { program, MixedNumeric } = await Tester.compile(t.code`
+      model ${t.model("MixedNumeric")} {
+        intValue: int32 = 100;
+        int64Value: int64 = 100;
+        floatValue: float = 100;
+        float64Value: float64 = 100;
+        decimalValue: decimal = 100;
+      }
+      `);
+
+      expect(getOutput(program, [<ClassDeclaration type={MixedNumeric} />])).toRenderTo(
+        `
+          from dataclasses import dataclass
+          from decimal import Decimal
+
+
+          @dataclass(kw_only=True)
+          class MixedNumeric:
+            int_value: int = 100
+            int64_value: int = 100
+            float_value: float = 100.0
+            float64_value: float = 100.0
+            decimal_value: Decimal = 100.0
+          
+          `,
+      );
+    });
+  });
+});

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

@@ -0,0 +1,67 @@
+import { typingModule } from "#python/builtins.js";
+import { type Children } from "@alloy-js/core";
+import * as py from "@alloy-js/python";
+import { type ModelProperty, type Operation } from "@typespec/compiler";
+import { useTsp } from "../../../core/context/tsp-context.js";
+import { TypeExpression } from "../type-expression/type-expression.js";
+import { Method } from "./class-method.js";
+import { PrimitiveInitializer } from "./primitive-initializer.js";
+
+export interface ClassMemberProps {
+  type: ModelProperty | Operation;
+  doc?: Children;
+  optional?: boolean;
+  methodType?: "method" | "class" | "static";
+  abstract?: boolean;
+}
+
+/**
+ * Creates the class member for the property.
+ * @param props - The props for the class member.
+ * @returns The class member.
+ */
+export function ClassMember(props: ClassMemberProps) {
+  const { $ } = useTsp();
+  const namer = py.usePythonNamePolicy();
+  const name = namer.getName(props.type.name, "class-member");
+  const doc = props.doc ?? $.type.getDoc(props.type);
+
+  if ($.modelProperty.is(props.type)) {
+    // Map never-typed properties to typing.Never
+
+    const unpackedType = props.type.type;
+    const isOptional = props.optional ?? props.type.optional ?? false;
+    const defaultValue = props.type.defaultValue;
+    const initializer = defaultValue ? (
+      <PrimitiveInitializer defaultValue={defaultValue} propertyType={unpackedType} />
+    ) : undefined;
+    const unpackedTypeNode: Children = <TypeExpression type={unpackedType} />;
+    const typeNode = isOptional ? (
+      <py.TypeReference
+        refkey={typingModule["."].Optional}
+        typeArgs={[unpackedTypeNode]}
+      ></py.TypeReference>
+    ) : (
+      unpackedTypeNode
+    );
+
+    const classMemberProps = {
+      doc,
+      name,
+      optional: isOptional,
+      ...(typeNode ? { type: typeNode } : {}),
+      ...(initializer ? { initializer } : {}),
+      omitNone: !isOptional,
+    };
+    return <py.VariableDeclaration {...classMemberProps} />;
+  }
+
+  if ($.operation.is(props.type)) {
+    return (
+      <Method type={props.type} doc={doc} methodType={props.methodType} abstract={props.abstract} />
+    );
+  }
+
+  // If type is neither ModelProperty nor Operation, return empty fragment
+  return <></>;
+}

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

@@ -0,0 +1,250 @@
+import { Tester } from "#test/test-host.js";
+import { getProgram } from "#test/utils.js";
+import * as py from "@alloy-js/python";
+import { t } from "@typespec/compiler/testing";
+import { describe, expect, it } from "vitest";
+import { ClassDeclaration } from "../../../../src/python/components/class-declaration/class-declaration.js";
+import { Method } from "../../../../src/python/components/class-declaration/class-method.js";
+import { getOutput } from "../../test-utils.js";
+
+describe("interface methods with a `type` prop", () => {
+  it("creates a class method from an interface method", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      @test op ${t.op("getName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ClassDeclaration name="basicInterface">
+          <Method async type={getName} />
+        </ClassDeclaration>,
+      ]),
+    ).toRenderTo(`
+      class BasicInterface:
+        async def get_name(self, id: str) -> str:
+          pass
+
+
+    `);
+  });
+
+  it("creates a class method that is a classmethod", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      @test op ${t.op("getName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ClassDeclaration name="basicInterface">
+          <Method async type={getName} methodType="class" />
+        </ClassDeclaration>,
+      ]),
+    ).toRenderTo(`
+      class BasicInterface:
+        @classmethod
+        async def get_name(cls, id: str) -> str:
+          pass
+
+
+    `);
+  });
+
+  it("creates a class method that is a staticmethod", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      @test op ${t.op("getName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ClassDeclaration name="basicInterface">
+          <Method async type={getName} methodType="static" />
+        </ClassDeclaration>,
+      ]),
+    ).toRenderTo(`
+      class BasicInterface:
+        @staticmethod
+        async def get_name(id: str) -> str:
+          pass
+
+
+    `);
+  });
+
+  it("creates an async class method from an asyncinterface method", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      @test op ${t.op("getName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ClassDeclaration name="basicInterface">
+          <Method async type={getName} />
+        </ClassDeclaration>,
+      ]),
+    ).toRenderTo(`
+      class BasicInterface:
+        async def get_name(self, id: str) -> str:
+          pass
+
+
+    `);
+  });
+
+  it("can append extra keyword-only parameters", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      @test op ${t.op("getName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ClassDeclaration name="basicInterface">
+          <Method type={getName} parameters={[{ name: "foo", type: "string" }]} />
+        </ClassDeclaration>,
+      ]),
+    ).toRenderTo(`
+      class BasicInterface:
+        def get_name(self, id: str, *, foo: str) -> str:
+          pass
+
+
+      `);
+  });
+
+  it("can add extra keyword-only parameters", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      @test op ${t.op("getName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ClassDeclaration name="basicInterface">
+          <Method type={getName} parameters={[{ name: "foo", type: "string" }]} />
+        </ClassDeclaration>,
+      ]),
+    ).toRenderTo(`
+      class BasicInterface:
+        def get_name(self, id: str, *, foo: str) -> str:
+          pass
+
+
+      `);
+  });
+
+  it("can replace parameters with raw params provided", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      @test op ${t.op("getName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ClassDeclaration name="basicInterface">
+          <Method
+            type={getName}
+            replaceParameters={true}
+            parameters={[
+              { name: "foo", type: "string" },
+              { name: "bar", type: "number" },
+            ]}
+          />
+        </ClassDeclaration>,
+      ]),
+    ).toRenderTo(`
+      class BasicInterface:
+        def get_name(self, *, foo: str, bar: float) -> str:
+          pass
+
+
+      `);
+  });
+
+  it("can replace parameters with params having defaults (requires * marker)", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      @test op ${t.op("getName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ClassDeclaration name="basicInterface">
+          <Method
+            type={getName}
+            replaceParameters={true}
+            parameters={[
+              { name: "foo", type: "string", default: <py.Atom jsValue={"default"} /> },
+              { name: "bar", type: "number", default: <py.Atom jsValue={42} /> },
+            ]}
+          />
+        </ClassDeclaration>,
+      ]),
+    ).toRenderTo(`
+      class BasicInterface:
+        def get_name(self, *, foo: str = "default", bar: float = 42) -> str:
+          pass
+
+
+      `);
+  });
+
+  it("can override return type in a class method", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      @test op ${t.op("getName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ClassDeclaration name="basicInterface">
+          <Method type={getName} returnType="ASpecialString" />
+        </ClassDeclaration>,
+      ]),
+    ).toRenderTo(`
+      class BasicInterface:
+        def get_name(self, id: str) -> ASpecialString:
+          pass
+
+
+      `);
+  });
+
+  it("can override method name in a class method", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      @test op ${t.op("getName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ClassDeclaration name="basicInterface">
+          <Method type={getName} name="get_name_custom" />
+        </ClassDeclaration>,
+      ]),
+    ).toRenderTo(`
+      class BasicInterface:
+        def get_name_custom(self, id: str) -> str:
+          pass
+
+
+      `);
+  });
+});
+
+describe("interface methods without a `type` prop", () => {
+  it("renders a plain interface method from a class method without a `type` prop", async () => {
+    const program = await getProgram("");
+
+    expect(
+      getOutput(program, [
+        <ClassDeclaration name="basicInterface">
+          <Method
+            name="plainMethod"
+            parameters={[{ name: "param1", type: "string" }]}
+            returnType="number"
+          />
+        </ClassDeclaration>,
+      ]),
+    ).toRenderTo(`
+      class BasicInterface:
+        def plain_method(self, param1: string) -> number:
+          pass
+
+
+      `);
+  });
+});