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

package/src/python/components/protocol-declaration/callable-parameters.tsx

@@ -0,0 +1,44 @@
+import { refkey } from "@alloy-js/core";
+import * as py from "@alloy-js/python";
+import type { Operation } from "@typespec/compiler";
+import { useTsp } from "../../../core/context/tsp-context.js";
+import { buildParameterDescriptor } from "../../utils/operation.js";
+
+export interface CallableParametersProps {
+  /**
+   * The operation to extract parameters from.
+   */
+  type: Operation;
+}
+
+/**
+ * Builds parameter descriptors for a callable (method/function) from an Operation's parameters.
+ *
+ * Iterates over the operation's parameters model and creates ParameterDescriptor objects
+ * with name, type expression, and default value (handles both explicit defaults and
+ * optional parameters without defaults which get `= None`).
+ *
+ * @returns Array of ParameterDescriptor objects for use with py.MethodDeclaration or similar.
+ *
+ * @example
+ * ```tsx
+ * const params = CallableParameters({ type: operation });
+ * <py.MethodDeclaration name="foo" parameters={params} />
+ * ```
+ */
+export function CallableParameters(props: CallableParametersProps): py.ParameterDescriptor[] {
+  const { $ } = useTsp();
+  const paramsModel = props.type.parameters;
+
+  if (!paramsModel) {
+    return [];
+  }
+
+  const parameters: py.ParameterDescriptor[] = [];
+
+  for (const prop of $.model.getProperties(paramsModel).values()) {
+    parameters.push(buildParameterDescriptor(prop, refkey()));
+  }
+
+  return parameters;
+}

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

@@ -0,0 +1,2 @@
+export * from "./callable-parameters.js";
+export * from "./protocol-declaration.js";

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

@@ -0,0 +1,106 @@
+import { TypeExpression } from "#python/components/type-expression/type-expression.js";
+import { Tester } from "#test/test-host.js";
+import { t } from "@typespec/compiler/testing";
+import { describe, expect, it } from "vitest";
+import { getOutput } from "../../test-utils.js";
+import { ProtocolDeclaration } from "./protocol-declaration.js";
+
+describe("Python ProtocolDeclaration", () => {
+  it("emits a callback Protocol for an operation", async () => {
+    const { program, getName, getOtherName } = await Tester.compile(t.code`
+      op ${t.op("getName")}(id: string): string;
+      op ${t.op("getOtherName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ProtocolDeclaration type={getName} />,
+        <ProtocolDeclaration type={getOtherName} />,
+      ]),
+    ).toRenderTo(`
+      from typing import Protocol
+
+
+      class GetName(Protocol):
+        def __call__(self, id: str) -> str:
+          ...
+
+
+
+      class GetOtherName(Protocol):
+        def __call__(self, id: str) -> str:
+          ...
+
+
+      `);
+  });
+
+  it("emits no return annotation when return type omitted", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      op ${t.op("getName")}(id: string): string;
+    `);
+
+    // Create a shallow clone without returnType to simulate missing return info
+    const getNameNoReturn: any = { ...(getName as any) };
+    delete getNameNoReturn.returnType;
+
+    expect(getOutput(program, [<ProtocolDeclaration type={getNameNoReturn} />])).toRenderTo(`
+      from typing import Protocol
+
+
+      class GetName(Protocol):
+        def __call__(self, id: str):
+          ...
+
+      
+      `);
+  });
+
+  it("emits a Protocol for a TypeSpec interface (methods only)", async () => {
+    const { program, Greeter } = await Tester.compile(t.code`
+      interface ${t.interface("Greeter")} {
+        op getName(id: string): string;
+        op getOtherName(id: string): string;
+      }
+    `);
+
+    expect(getOutput(program, [<ProtocolDeclaration type={Greeter} />])).toRenderTo(`
+      from typing import Protocol
+
+
+      class Greeter(Protocol):
+        def get_name(self, id: str) -> str:
+          ...
+
+        def get_other_name(self, id: str) -> str:
+          ...
+      
+      
+      `);
+  });
+
+  it("emits both a Protocol and a Callable for the same operation", async () => {
+    const { program, getName } = await Tester.compile(t.code`
+      op ${t.op("getName")}(id: string): string;
+    `);
+
+    expect(
+      getOutput(program, [
+        <ProtocolDeclaration type={getName} />,
+        <TypeExpression type={getName} />,
+      ]),
+    ).toRenderTo(`
+      from typing import Callable
+      from typing import Protocol
+
+
+      class GetName(Protocol):
+        def __call__(self, id: str) -> str:
+          ...
+
+      
+      
+      Callable[[str], str]
+      `);
+  });
+});

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

@@ -0,0 +1,73 @@
+import { useTsp } from "#core/context/tsp-context.js";
+import { typingModule } from "#python/builtins.js";
+import { TypeExpression } from "#python/components/type-expression/type-expression.js";
+import { reportPythonDiagnostic } from "#python/lib.js";
+import { declarationRefkeys } from "#python/utils/refkey.js";
+import { mapJoin } from "@alloy-js/core";
+import * as py from "@alloy-js/python";
+import type { Interface, Operation, Type } from "@typespec/compiler";
+import { CallableParameters } from "./callable-parameters.js";
+
+export interface ProtocolDeclarationProps extends Omit<py.ClassDeclarationProps, "name"> {
+  type: Interface | Operation;
+  name?: string;
+}
+
+export function ProtocolDeclaration(props: ProtocolDeclarationProps) {
+  const { $ } = useTsp();
+
+  const refkeys = declarationRefkeys(props.refkey, props.type);
+  const protocolBase = typingModule["."]["Protocol"];
+
+  const namePolicy = py.usePythonNamePolicy();
+  const originalName = props.name ?? (props.type as any)?.name ?? "";
+  const name = namePolicy.getName(originalName, "class");
+
+  // Interfaces will be converted to Protocols with method stubs for operations
+  if ((props.type as any)?.kind === "Interface") {
+    const iface = props.type as Interface;
+    const operations = ((iface as any).operations ?? new Map()) as Map<string, any>;
+    const methods = mapJoin(
+      () => Array.from(operations.values()) as any[],
+      (op: any) => {
+        const methodName = namePolicy.getName(op.name, "function");
+        const prm = CallableParameters({ type: op as Operation }); // self injected by MethodDeclaration
+        const ret = (op as any)?.returnType ? (
+          <TypeExpression type={(op as Operation).returnType as Type} />
+        ) : undefined;
+        return (
+          <py.MethodDeclaration name={methodName} parameters={prm} returnType={ret}>
+            ...
+          </py.MethodDeclaration>
+        );
+      },
+    );
+    return (
+      <py.ClassDeclaration name={name} bases={[protocolBase]} refkey={refkeys} doc={props.doc}>
+        {methods}
+      </py.ClassDeclaration>
+    );
+  }
+
+  if ((props.type as any)?.kind !== "Operation") {
+    reportPythonDiagnostic($.program, {
+      code: "python-unsupported-type",
+      target: props.type as any,
+    });
+    return <></>;
+  }
+
+  // Operations will be converted to Callback protocol using a dunder __call__ method
+  const op = props.type as Operation;
+  const cbParams = CallableParameters({ type: op });
+  const cbReturn = (op as any)?.returnType ? (
+    <TypeExpression type={op.returnType as Type} />
+  ) : undefined;
+  return (
+    <py.ClassDeclaration name={name} bases={[protocolBase]} refkey={refkeys} doc={props.doc}>
+      <py.DunderMethodDeclaration name="__call__" returnType={cbReturn} parameters={cbParams}>
+        ...
+      </py.DunderMethodDeclaration>
+    </py.ClassDeclaration>
+  );
+}

package/src/python/components/record-expression/index.ts

@@ -0,0 +1 @@
+export * from "./record-expression.js";

package/src/python/components/record-expression/record-expression.test.tsx

@@ -0,0 +1,14 @@
+import { Tester } from "#test/test-host.js";
+import { d } from "@alloy-js/core/testing";
+import { t } from "@typespec/compiler/testing";
+import { expect, it } from "vitest";
+import { getOutput } from "../../test-utils.js";
+import { TypeExpression } from "../type-expression/type-expression.js";
+
+it("maps Record to Python dict", async () => {
+  const { program, TestRecord } = await Tester.compile(t.code`
+    alias ${t.type("TestRecord")} = Record<boolean>;
+  `);
+
+  expect(getOutput(program, [<TypeExpression type={TestRecord} />])).toRenderTo(d`dict[str, bool]`);
+});

package/src/python/components/record-expression/record-expression.tsx

@@ -0,0 +1,13 @@
+import { code } from "@alloy-js/core";
+import type { Type } from "@typespec/compiler";
+import { TypeExpression } from "../type-expression/type-expression.js";
+
+export interface RecordExpressionProps {
+  elementType: Type;
+}
+
+export function RecordExpression({ elementType }: RecordExpressionProps) {
+  return code`
+  dict[str, ${(<TypeExpression type={elementType} />)}]
+  `;
+}

package/src/python/components/type-alias-declaration/index.ts

@@ -0,0 +1 @@
+export * from "./type-alias-declaration.js";

package/src/python/components/type-alias-declaration/type-alias-declaration.test.tsx

@@ -0,0 +1,117 @@
+import { Tester } from "#test/test-host.js";
+import { t } from "@typespec/compiler/testing";
+import { describe, expect, it } from "vitest";
+import { getOutput } from "../../test-utils.js";
+import { TypeAliasDeclaration } from "./type-alias-declaration.js";
+
+describe("Python Declaration equivalency to Type Alias", () => {
+  describe("Type Alias Declaration bound to Typespec Scalar", () => {
+    describe("Scalar extends utcDateTime", () => {
+      it("creates a type alias declaration for a utcDateTime without encoding", async () => {
+        const { program, MyDate } = await Tester.compile(t.code`
+          scalar ${t.scalar("MyDate")} extends utcDateTime;
+        `);
+
+        expect(getOutput(program, [<TypeAliasDeclaration type={MyDate} />])).toRenderTo(`
+          from datetime import datetime
+          from typing import TypeAlias
+
+
+          my_date: TypeAlias = datetime`);
+      });
+
+      it("creates a type alias declaration with doc", async () => {
+        const { program, MyDate } = await Tester.compile(t.code`
+          /**
+           * Type to represent a date
+           */
+          scalar ${t.scalar("MyDate")} extends utcDateTime;
+        `);
+
+        expect(getOutput(program, [<TypeAliasDeclaration type={MyDate} />])).toRenderTo(`
+          from datetime import datetime
+          from typing import TypeAlias
+
+
+          # Type to represent a date
+          my_date: TypeAlias = datetime`);
+      });
+
+      it("can override JSDoc", async () => {
+        const { program, MyDate } = await Tester.compile(t.code`
+          /**
+           * Type to represent a date
+           */
+          scalar ${t.scalar("MyDate")} extends utcDateTime;
+        `);
+
+        expect(getOutput(program, [<TypeAliasDeclaration doc={"Overridden Doc"} type={MyDate} />]))
+          .toRenderTo(`
+          from datetime import datetime
+          from typing import TypeAlias
+
+
+          # Overridden Doc
+          my_date: TypeAlias = datetime`);
+      });
+
+      it("creates a type alias declaration for a utcDateTime with unixTimeStamp encoding", async () => {
+        const { program, MyDate } = await Tester.compile(t.code`
+          @encode("unixTimestamp", int32)
+          scalar ${t.scalar("MyDate")} extends utcDateTime;
+        `);
+
+        expect(getOutput(program, [<TypeAliasDeclaration type={MyDate} />])).toRenderTo(`
+          from datetime import datetime
+          from typing import TypeAlias
+
+
+          my_date: TypeAlias = datetime`);
+      });
+
+      it("creates a type alias declaration for a utcDateTime with rfc7231 encoding", async () => {
+        const { program, MyDate } = await Tester.compile(t.code`
+          @encode("rfc7231")
+          scalar ${t.scalar("MyDate")} extends utcDateTime;
+        `);
+
+        expect(getOutput(program, [<TypeAliasDeclaration type={MyDate} />])).toRenderTo(`
+          from datetime import datetime
+          from typing import TypeAlias
+
+
+          my_date: TypeAlias = datetime`);
+      });
+
+      it("creates a type alias declaration for a utcDateTime with rfc3339 encoding", async () => {
+        const { program, MyDate } = await Tester.compile(t.code`
+          @encode("rfc3339")
+          scalar ${t.scalar("MyDate")} extends utcDateTime;
+        `);
+
+        expect(getOutput(program, [<TypeAliasDeclaration type={MyDate} />])).toRenderTo(`
+          from datetime import datetime
+          from typing import TypeAlias
+
+
+          my_date: TypeAlias = datetime`);
+      });
+    });
+  });
+
+  describe("Type Alias Declaration for Operation (Callable)", () => {
+    it("creates a type alias for an operation type reference", async () => {
+      const { program, Handler } = await Tester.compile(t.code`
+        op handleRequest(id: string): string;
+        alias ${t.type("Handler")} = handleRequest;
+      `);
+
+      expect(getOutput(program, [<TypeAliasDeclaration type={Handler} />])).toRenderTo(`
+        from typing import Callable
+        from typing import TypeAlias
+
+
+        handle_request: TypeAlias = Callable[[str], str]`);
+    });
+  });
+});

package/src/python/components/type-alias-declaration/type-alias-declaration.tsx

@@ -0,0 +1,67 @@
+import { useTsp } from "#core/context/index.js";
+import * as py from "@alloy-js/python";
+import { isTemplateInstance, type Model, type Type } from "@typespec/compiler";
+import { reportDiagnostic } from "../../../lib.js";
+import { typingModule } from "../../builtins.js";
+import { declarationRefkeys } from "../../utils/refkey.js";
+import { ClassDeclaration } from "../class-declaration/class-declaration.js";
+import { TypeExpression } from "../type-expression/type-expression.js";
+
+export interface TypedAliasDeclarationProps extends Omit<py.BaseDeclarationProps, "name"> {
+  type: Type;
+  name?: string;
+}
+
+/**
+ * Create a Python type alias declaration. Pass the `type` prop to emit the
+ * type alias as the provided TypeSpec type.
+ *
+ * For template instances (e.g., `alias StringResponse = Response<string>`),
+ * this emits a dataclass instead of a type alias, since Python doesn't support
+ * parameterized type aliases the way TypeScript does.
+ */
+export function TypeAliasDeclaration(props: TypedAliasDeclarationProps) {
+  const { $ } = useTsp();
+
+  const originalName =
+    props.name ??
+    ("name" in props.type && typeof props.type.name === "string" ? props.type.name : "");
+
+  if (!originalName || originalName === "") {
+    reportDiagnostic($.program, { code: "type-declaration-missing-name", target: props.type });
+  }
+
+  const doc = props.doc ?? $.type.getDoc(props.type);
+  const refkeys = declarationRefkeys(props.refkey, props.type);
+
+  // For Model template instances (e.g., alias StringResponse = Response<string>),
+  // emit as a dataclass since Python doesn't support parameterized type aliases.
+  // TypeSpec templates are macros that expand to concrete types.
+  if ($.model.is(props.type) && isTemplateInstance(props.type)) {
+    const namePolicy = py.usePythonNamePolicy();
+    const plausibleName = $.type.getPlausibleName(props.type as Model);
+    const name = props.name ?? namePolicy.getName(plausibleName, "class");
+
+    return (
+      <ClassDeclaration doc={doc} type={props.type} name={name} refkey={refkeys}>
+        {props.children}
+      </ClassDeclaration>
+    );
+  }
+
+  // For other types (scalars, unions, operations), emit as a type alias
+  const name = py.usePythonNamePolicy().getName(originalName, "variable");
+
+  return (
+    <py.VariableDeclaration
+      doc={doc}
+      name={name}
+      refkey={refkeys}
+      omitNone={true}
+      type={typingModule["."]["TypeAlias"]}
+      initializer={<TypeExpression type={props.type} noReference />}
+    >
+      {props.children}
+    </py.VariableDeclaration>
+  );
+}

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

@@ -0,0 +1 @@
+export * from "./type-declaration.js";

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

@@ -0,0 +1,58 @@
+import { Tester } from "#test/test-host.js";
+import { d } from "@alloy-js/core/testing";
+import { t } from "@typespec/compiler/testing";
+import { describe, expect, it } from "vitest";
+import { getOutput } from "../../test-utils.js";
+import { TypeDeclaration } from "./type-declaration.js";
+
+describe("Python TypeDeclaration dispatcher", () => {
+  it("dispatches to EnumDeclaration for enums", async () => {
+    const { program, Foo } = await Tester.compile(t.code`
+      enum ${t.enum("Foo")} {
+        one: 1,
+        two: 2,
+        three: 3
+      }
+    `);
+
+    const output = getOutput(program, [<TypeDeclaration type={Foo} />]);
+    expect(output).toRenderTo(d`
+      from enum import IntEnum
+
+
+      class Foo(IntEnum):
+        ONE = 1
+        TWO = 2
+        THREE = 3
+
+
+    `);
+  });
+
+  it("dispatches scalars to TypeAliasDeclaration", async () => {
+    const { program, MyDate } = await Tester.compile(t.code`
+      scalar ${t.scalar("MyDate")} extends utcDateTime;
+    `);
+
+    const output = getOutput(program, [<TypeDeclaration type={MyDate} />]);
+    expect(output).toRenderTo(d`
+      from datetime import datetime
+      from typing import TypeAlias
+
+
+      my_date: TypeAlias = datetime`);
+  });
+
+  it("dispatches arrays (model is Array<T>) to type alias with list[T]", async () => {
+    const { program, Items } = await Tester.compile(t.code`
+      model ${t.model("Items")} is Array<int32>;
+    `);
+
+    const output = getOutput(program, [<TypeDeclaration type={Items} />]);
+    expect(output).toRenderTo(d`
+      from typing import TypeAlias
+
+
+      items: TypeAlias = list[int]`);
+  });
+});

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

@@ -0,0 +1,26 @@
+import { useTsp } from "#core/context/index.js";
+import * as py from "@alloy-js/python";
+import type { Type } from "@typespec/compiler";
+import { EnumDeclaration } from "../enum-declaration/enum-declaration.js";
+import { TypeAliasDeclaration } from "../type-alias-declaration/type-alias-declaration.js";
+
+export interface TypeDeclarationProps extends Omit<py.BaseDeclarationProps, "name"> {
+  name?: string;
+  type: Type;
+}
+
+/**
+ * Single entry point to declare a Python symbol for any TypeSpec `Type`.
+ */
+export function TypeDeclaration(props: TypeDeclarationProps) {
+  const { $ } = useTsp();
+  const { type, ...restProps } = props;
+  const doc = props.doc ?? $.type.getDoc(type);
+  switch (type.kind) {
+    case "Enum":
+      return <EnumDeclaration doc={doc} type={type} {...restProps} />;
+    default:
+      // All other kinds map to a Python type alias using TypeExpression
+      return <TypeAliasDeclaration doc={doc} type={type} {...restProps} />;
+  }
+}

package/src/python/components/type-expression/index.ts

@@ -0,0 +1 @@
+export * from "./type-expression.js";