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

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

@@ -0,0 +1,333 @@
+import { Experimental_OverridableComponent } from "#core/components/index.js";
+import { useTsp } from "#core/context/index.js";
+import { reportPythonDiagnostic } from "#python/lib.js";
+import { code, For, List, mapJoin } from "@alloy-js/core";
+import * as py from "@alloy-js/python";
+import {
+  isNeverType,
+  type IntrinsicType,
+  type Model,
+  type Scalar,
+  type Type,
+} from "@typespec/compiler";
+import type { TemplateParameterDeclarationNode } from "@typespec/compiler/ast";
+import type { Typekit } from "@typespec/compiler/typekit";
+import { datetimeModule, decimalModule, typingModule } from "../../builtins.js";
+import { efRefkey } from "../../utils/refkey.js";
+import { ArrayExpression } from "../array-expression/array-expression.js";
+import { RecordExpression } from "../record-expression/record-expression.js";
+
+export interface TypeExpressionProps {
+  type: Type;
+
+  /**
+   * Whether to disallow references. Setting this will force the type to be
+   * emitted inline, even if it is a declaration that would otherwise be
+   * referenced.
+   */
+  noReference?: boolean;
+}
+
+export function TypeExpression(props: TypeExpressionProps) {
+  const { $ } = useTsp();
+  const type = props.type;
+  if (!props.noReference && isDeclaration($, type)) {
+    return (
+      <Experimental_OverridableComponent reference type={type}>
+        <py.Reference refkey={efRefkey(type)} />
+      </Experimental_OverridableComponent>
+    );
+  }
+
+  switch (type.kind) {
+    case "Scalar": // Custom types based on primitives (Intrinsics)
+    case "Intrinsic": // Language primitives like `string`, `number`, etc.
+      if (isNeverType(type)) {
+        return typingModule["."]["Never"];
+      }
+      return <>{getScalarIntrinsicExpression($, type)}</>;
+    case "Boolean":
+    case "Number":
+    case "String":
+      // Single literal values are wrapped in Literal[...]
+      return (
+        <>
+          {typingModule["."]["Literal"]}[{formatLiteralValue(type)}]
+        </>
+      );
+    case "Tuple":
+      return (
+        <>
+          tuple[
+          <For each={type.values} comma space>
+            {(element) => <TypeExpression type={element} />}
+          </For>
+          ]
+        </>
+      );
+    case "Union": {
+      const variants = Array.from((type as any).variants?.values?.() ?? []);
+
+      // Check if all variants are literals or named union variant refs with literal values
+      const isLiteralOrVariantRef = (t: Type): boolean => {
+        if (!t) return false;
+        if (isLiteral($, t)) return true;
+        // Named union variant with a literal inner value
+        if (t.kind === "UnionVariant" && (t as any).union?.name) {
+          return isLiteral($, (t as any).type);
+        }
+        return false;
+      };
+
+      const innerTypes = variants.map((v: any) => v.type);
+      if (innerTypes.every(isLiteralOrVariantRef)) {
+        // All literals - render as Literal[...]
+        const literalValues = variants
+          .map((v: any) => {
+            const innerType = v.type;
+            // Named union variant ref with literal value
+            if (innerType.kind === "UnionVariant" && innerType.union?.name) {
+              const variantName = String(innerType.name).toUpperCase();
+              return code`${efRefkey(innerType.union)}.${variantName}`;
+            }
+            if (isLiteral($, innerType)) {
+              return formatLiteralValue(innerType);
+            }
+            return undefined;
+          })
+          .filter(Boolean);
+
+        return (
+          <>
+            {typingModule["."]["Literal"]}[<List children={literalValues} joiner=", " />]
+          </>
+        );
+      }
+
+      // Not all literals - render as union type
+      return mapJoin(
+        () => variants,
+        (v: any) => <TypeExpression type={v.type} />,
+        { joiner: " | " },
+      );
+    }
+    case "UnionVariant": {
+      // Union variant from a named union with a literal value
+      if (type.union && (type.union as any).name && isLiteral($, type.type)) {
+        // Use the variant's name (e.g., "red", "active"), converted to UPPER_CASE by the enum
+        const variantName = String(type.name).toUpperCase();
+        return (
+          <>
+            {typingModule["."]["Literal"]}[{efRefkey(type.union)}.{variantName}]
+          </>
+        );
+      }
+      // Unnamed union variant or non-literal value, unwrap to its inner type
+      return <TypeExpression type={type.type} />;
+    }
+    case "ModelProperty":
+      return <TypeExpression type={type.type} />;
+    case "Model":
+      if ($.array.is(type)) {
+        const elementType = type.indexer!.value;
+        return <ArrayExpression elementType={elementType} />;
+      }
+
+      if ($.record.is(type)) {
+        const elementType = (type as Model).indexer!.value;
+        return <RecordExpression elementType={elementType} />;
+      }
+
+      // TODO: When TypeSpec adds true generics support, handle generic type references here.
+      // Currently, TypeSpec templates are macros that expand to concrete types, so template
+      // instances (e.g., Response<string>) are treated as regular concrete types, not as
+      // parameterized generic types (e.g., Response[str]).
+      // When generics are implemented, this is where we would render: ClassName[TypeArg, ...]
+
+      // Regular named models should be handled as references
+      if (type.name) {
+        return (
+          <Experimental_OverridableComponent reference type={type}>
+            <py.Reference refkey={efRefkey(type)} />
+          </Experimental_OverridableComponent>
+        );
+      }
+
+      reportPythonDiagnostic($.program, { code: "python-unsupported-type", target: type });
+      return <></>;
+    case "TemplateParameter":
+      return code`${String((type.node as TemplateParameterDeclarationNode).id.sv)}`;
+
+    case "Operation": {
+      // Render function types as typing.Callable[[ArgTypes...], ReturnType]
+      // If parameters cannot be enumerated, fall back to Callable[..., ReturnType]
+      let paramTypes: Type[] | null = null;
+      const op: any = type as any;
+      if (op.parameters) {
+        try {
+          const { $ } = useTsp();
+          const modelProps = $.model.getProperties(op.parameters);
+          paramTypes = Array.from(modelProps.values()).map((p: any) => p.type);
+        } catch {
+          // Unknown/unsupported params shape
+          paramTypes = null;
+        }
+      } else {
+        paramTypes = [];
+      }
+
+      return (
+        <>
+          {typingModule["."]["Callable"]}[
+          {paramTypes === null ? (
+            <>...</>
+          ) : paramTypes.length > 0 ? (
+            <>
+              [
+              <For each={paramTypes} comma space>
+                {(t) => <TypeExpression type={t} />}
+              </For>
+              ]
+            </>
+          ) : (
+            <>[]</>
+          )}
+          {", "}
+          <TypeExpression type={(type as any).returnType} />]
+        </>
+      );
+    }
+    default:
+      reportPythonDiagnostic($.program, { code: "python-unsupported-type", target: type });
+      // Return empty fragment - the diagnostic has already been reported
+      return <></>;
+  }
+}
+
+/**
+ * Checks if a type is a literal (string, numeric, or boolean).
+ */
+function isLiteral($: Typekit, type: Type): boolean {
+  return $.literal.isString(type) || $.literal.isNumeric(type) || $.literal.isBoolean(type);
+}
+
+/**
+ * Formats a literal type value for use in Python's Literal[...] syntax.
+ */
+function formatLiteralValue(type: { kind: string; value: unknown }): string {
+  switch (type.kind) {
+    case "String":
+      return JSON.stringify(type.value);
+    case "Boolean":
+      return type.value ? "True" : "False";
+    case "Number":
+      return String(type.value);
+    default:
+      return String(type.value);
+  }
+}
+
+const intrinsicNameToPythonType = new Map<string, string | null>([
+  // Core types
+  ["unknown", "Any"], // Matches Python's `Any`
+  ["string", "str"], // Matches Python's `str`
+  ["boolean", "bool"], // Matches Python's `bool`
+  ["null", "None"], // Matches Python's `None`
+  ["void", "None"], // Matches Python's `None`
+  ["never", "Never"], // Matches Python's `Never`
+  ["bytes", "bytes"], // Matches Python's `bytes`
+
+  // Numeric types
+  ["numeric", "number"], // Parent type for all numeric types
+  ["integer", "int"], // Broad integer category, maps to `int`
+  ["float", "float"], // Broad float category, maps to `float`
+  ["decimal", "Decimal"], // Broad decimal category, maps to `Decimal`
+  ["decimal128", "Decimal"], // 128-bit decimal category, maps to `Decimal`
+  ["int64", "int"], // Use `int` to handle large 64-bit integers
+  ["int32", "int"], // 32-bit integer fits in Python's `int`
+  ["int16", "int"], // 16-bit integer
+  ["int8", "int"], // 8-bit integer
+  ["safeint", "int"], // Safe integer fits within Python limits
+  ["uint64", "int"], // Use `int` for unsigned 64-bit integers
+  ["uint32", "int"], // 32-bit unsigned integer
+  ["uint16", "int"], // 16-bit unsigned integer
+  ["uint8", "int"], // 8-bit unsigned integer
+  ["float32", "float"], // Maps to Python's `float`
+  ["float64", "float"], // Maps to Python's `float`.
+
+  // Date and time types
+  ["plainDate", "str"], // Use `str` for plain calendar dates
+  ["plainTime", "str"], // Use `str` for plain clock times
+  ["utcDateTime", "datetime"], // Use `datetime` for UTC date-times
+  ["offsetDateTime", "str"], // Use `str` for timezone-specific date-times
+  ["duration", "str"], // Duration as an ISO 8601 string or custom format
+
+  // String types
+  ["url", "str"], // Matches Python's `str`
+]);
+
+const pythonTypeToImport = new Map<string, any>([
+  ["Any", typingModule["."]["Any"]],
+  ["Never", typingModule["."]["Never"]],
+  ["datetime", datetimeModule["."]["datetime"]],
+  ["Decimal", decimalModule["."]["Decimal"]],
+]);
+
+function getScalarIntrinsicExpression($: Typekit, type: Scalar | IntrinsicType): string | null {
+  let intrinsicName: string;
+  if ($.scalar.is(type)) {
+    if ($.scalar.isUtcDateTime(type) || $.scalar.extendsUtcDateTime(type)) {
+      const encoding = $.scalar.getEncoding(type);
+      intrinsicName = "utcDateTime";
+      switch (encoding?.encoding) {
+        case "unixTimestamp":
+        case "rfc7231":
+        case "rfc3339":
+        default:
+          intrinsicName = `utcDateTime`;
+          break;
+      }
+    }
+    intrinsicName = $.scalar.getStdBase(type)?.name ?? "";
+  } else {
+    intrinsicName = type.name;
+  }
+
+  let pythonType = intrinsicNameToPythonType.get(intrinsicName);
+  const importModule = pythonTypeToImport.get(pythonType ?? "");
+  pythonType = importModule ? importModule : pythonType;
+
+  if (!pythonType) {
+    reportPythonDiagnostic($.program, { code: "python-unsupported-scalar", target: type });
+    return "any";
+  }
+
+  return pythonType;
+}
+
+// TODO: When TypeSpec adds true generics support, add helper to detect generic type instances.
+// Currently, TypeSpec templates expand to concrete types at compile time, so we treat all
+// template instances as regular concrete types.
+
+function isDeclaration($: Typekit, type: Type): boolean {
+  switch (type.kind) {
+    case "Namespace":
+    case "Interface":
+    case "Enum":
+    case "Operation":
+    case "EnumMember":
+    case "UnionVariant":
+      return false;
+
+    case "Model":
+      if ($.array.is(type) || $.record.is(type)) {
+        return false;
+      }
+
+      return Boolean(type.name);
+    case "Union":
+      return Boolean(type.name);
+    default:
+      return false;
+  }
+}

package/src/python/index.ts

@@ -0,0 +1,3 @@
+export * from "./builtins.js";
+export * from "./components/index.js";
+export * from "./utils/index.js";

package/src/python/lib.ts

@@ -0,0 +1,40 @@
+import { createTypeSpecLibrary } from "@typespec/compiler";
+
+export const $pythonLib = createTypeSpecLibrary({
+  name: "emitter-framework",
+  diagnostics: {
+    "python-unsupported-scalar": {
+      severity: "warning",
+      messages: {
+        default: "Unsupported scalar type, falling back to Any",
+      },
+    },
+    "python-unsupported-type": {
+      severity: "error",
+      messages: {
+        default: "Unsupported type, falling back to Any",
+      },
+      description: "This type is not supported by the Python emitter",
+    },
+    "python-unsupported-model-discriminator": {
+      severity: "error",
+      messages: {
+        default:
+          "Unsupported model discriminator, falling back to not discriminating on serialization/deserialization",
+      },
+      description: "Discriminators at the model are not supported",
+    },
+    "python-unsupported-type-transform": {
+      severity: "error",
+      messages: {
+        default: "Unsupported type for transformation, falling back to not transforming this type",
+      },
+      description: "This type cannot be transformed",
+    },
+  },
+});
+
+export const {
+  reportDiagnostic: reportPythonDiagnostic,
+  createDiagnostic: createPythonDiagnostic,
+} = $pythonLib;

package/src/python/test-utils.tsx

@@ -0,0 +1,31 @@
+import { Output } from "#core/components/index.js";
+import { type Children } from "@alloy-js/core";
+import * as py from "@alloy-js/python";
+import type { Program } from "@typespec/compiler";
+import { abcModule, datetimeModule, decimalModule, typingModule } from "./builtins.js";
+
+export const renderOptions = {
+  printWidth: 80,
+  tabWidth: 4,
+};
+
+export function getOutput(program: Program, children: Children[]): Children {
+  const policy = py.createPythonNamePolicy();
+  return (
+    <Output
+      program={program}
+      externals={[
+        abcModule,
+        datetimeModule,
+        decimalModule,
+        typingModule,
+        py.abcModule,
+        py.dataclassesModule,
+        py.enumModule,
+      ]}
+      namePolicy={policy}
+    >
+      <py.SourceFile path="test.py">{children}</py.SourceFile>
+    </Output>
+  );
+}

package/src/python/utils/index.ts

@@ -0,0 +1,3 @@
+export * from "./operation.js";
+export * from "./refkey.js";
+export * from "./type.js";

package/src/python/utils/operation.ts

@@ -0,0 +1,161 @@
+import { typingModule } from "#python/builtins.js";
+import { refkey, type Children, type Refkey } from "@alloy-js/core";
+import * as py from "@alloy-js/python";
+import type { Model, ModelProperty, Operation, Type } from "@typespec/compiler";
+import { useTsp } from "../../core/index.js";
+import { Atom } from "../components/atom/atom.js";
+import { TypeExpression } from "../components/type-expression/type-expression.js";
+import { efRefkey } from "./refkey.js";
+
+export function getReturnType(
+  type: Operation,
+  options: { skipErrorFiltering: boolean } = { skipErrorFiltering: false },
+): Type {
+  const { $ } = useTsp();
+  let returnType = type.returnType;
+
+  if (!options.skipErrorFiltering && type.returnType.kind === "Union") {
+    returnType = $.union.filter(type.returnType, (variant) => !$.type.isError(variant.type));
+  }
+
+  return returnType;
+}
+
+export interface BuildParameterDescriptorsOptions {
+  params?: (py.ParameterDescriptor | string)[];
+  suffixRefkey?: Refkey;
+  /** If true, params replaces operation parameters instead of adding to them */
+  replaceParameters?: boolean;
+}
+
+/**
+ * Build a parameter descriptor array from a TypeSpec Model.
+ *
+ * Parameter ordering (unless replaceParameters is true):
+ * - Operation params without defaults: positional (e.g., URL path params)
+ * - "*" marker (if any keyword-only params exist)
+ * - Operation params with defaults: keyword-only (e.g., query params)
+ * - Additional params: keyword-only
+ */
+export function buildParameterDescriptors(
+  type: Model,
+  options: BuildParameterDescriptorsOptions = {},
+): (py.ParameterDescriptor | string)[] | undefined {
+  const { $ } = useTsp();
+  const suffixRefkey = options.suffixRefkey ?? refkey();
+  const optionsParams: py.ParameterDescriptor[] = normalizeParameters(options.params ?? []);
+
+  // If replaceParameters is true, ignore operation params and just return options params
+  // All replacement parameters are keyword-only (following "additional parameters are keyword-only" principle)
+  if (options.replaceParameters) {
+    const withoutDefaults = optionsParams.filter((p) => p.default === undefined);
+    const withDefaults = optionsParams.filter((p) => p.default !== undefined);
+
+    // Always add "*" marker since all replacement params should be keyword-only
+    const allParams: (py.ParameterDescriptor | string)[] =
+      optionsParams.length > 0 ? ["*", ...withoutDefaults, ...withDefaults] : [];
+
+    return allParams;
+  }
+
+  const modelProperties = $.model.getProperties(type);
+  const operationParams: py.ParameterDescriptor[] = [...modelProperties.values()].map((m) =>
+    buildParameterDescriptor(m, suffixRefkey),
+  );
+
+  // Split operation params: params without defaults are positional, params with defaults are keyword-only
+  const opParamsWithoutDefaults = operationParams.filter((p) => p.default === undefined);
+  const opParamsWithDefaults = operationParams.filter((p) => p.default !== undefined);
+
+  // Reorder additional params: params without defaults before params with defaults
+  const optionsWithoutDefaults = optionsParams.filter((p) => p.default === undefined);
+  const optionsWithDefaults = optionsParams.filter((p) => p.default !== undefined);
+
+  // Build final parameter list:
+  // - Operation params without defaults: positional (e.g., URL path params)
+  // - "*" marker (if there are keyword-only params)
+  // - Operation params with defaults: keyword-only (e.g., query params with defaults)
+  // - Additional params: keyword-only
+
+  // If there are no operation params at all, treat additional params without defaults as positional
+  const hasOperationParams = operationParams.length > 0;
+
+  const positionalParams = hasOperationParams
+    ? opParamsWithoutDefaults
+    : [...opParamsWithoutDefaults, ...optionsWithoutDefaults];
+
+  const keywordOnlyParams = hasOperationParams
+    ? [...optionsWithoutDefaults, ...opParamsWithDefaults, ...optionsWithDefaults]
+    : [...opParamsWithDefaults, ...optionsWithDefaults];
+
+  // Add "*" marker if we have keyword-only params
+  // This enforces that params with defaults are truly keyword-only
+  const allParams: (py.ParameterDescriptor | string)[] =
+    keywordOnlyParams.length > 0
+      ? [...positionalParams, "*", ...keywordOnlyParams]
+      : [...positionalParams];
+
+  return allParams;
+}
+
+/**
+ * Convert a TypeSpec ModelProperty into a Python ParameterDescriptor.
+ */
+export function buildParameterDescriptor(
+  modelProperty: ModelProperty,
+  suffixRefkey: Refkey,
+): py.ParameterDescriptor {
+  const { $ } = useTsp();
+  const namePolicy = py.usePythonNamePolicy();
+  const paramName = namePolicy.getName(modelProperty.name, "parameter");
+  const isOptional = modelProperty.optional || modelProperty.defaultValue !== undefined;
+  const doc = $.type.getDoc(modelProperty);
+  let defaultValueNode: Children | undefined = undefined;
+  const hasDefault =
+    modelProperty.defaultValue !== undefined && modelProperty.defaultValue !== null;
+  if (hasDefault) {
+    defaultValueNode = Atom({ value: (modelProperty as any).defaultValue });
+  } else if (isOptional) {
+    // Render Python None for optional parameters without explicit default
+    defaultValueNode = py.Atom({ jsValue: null }) as any;
+  }
+  return {
+    doc,
+    name: paramName,
+    refkey: efRefkey(modelProperty, suffixRefkey),
+    type: TypeExpression({ type: modelProperty.type }),
+    ...(defaultValueNode !== undefined ? { default: defaultValueNode } : {}),
+  };
+}
+
+const rawTypeMap = {
+  string: "str",
+  number: "float",
+  boolean: "bool",
+  any: typingModule["."]["Any"],
+  never: typingModule["."]["Never"],
+};
+
+/**
+ * Convert a parameter descriptor array to normalized parameter descriptors.
+ * String parameter names are converted to basic parameter descriptors.
+ */
+function normalizeParameters(
+  params: (py.ParameterDescriptor | string)[],
+): py.ParameterDescriptor[] {
+  if (!params) return [];
+
+  return params.map((param) => {
+    if (typeof param === "string") {
+      // Convert string names to parameter descriptors
+      return { name: param };
+    }
+    if (typeof (param as any).type === "string") {
+      return {
+        ...param,
+        type: rawTypeMap[param.type as keyof typeof rawTypeMap] ?? param.type,
+      } as py.ParameterDescriptor;
+    }
+    return param;
+  });
+}

package/src/python/utils/refkey.ts

@@ -0,0 +1,36 @@
+import { refkey as ayRefkey, type Refkey } from "@alloy-js/core";
+
+const refKeyPrefix = Symbol.for("emitter-framework:python");
+
+/**
+ * A wrapper around `refkey` that uses a custom symbol to avoid collisions with
+ * other libraries that use `refkey`.
+ *
+ * @remarks
+ *
+ * The underlying refkey function is called with the {@link refKeyPrefix} symbol as the first argument.
+ *
+ * @param args The parameters of the refkey.
+ * @returns A refkey object that can be used to identify the value.
+ */
+export function efRefkey(...args: unknown[]): Refkey {
+  if (args.length === 0) {
+    return ayRefkey(); // Generates a unique refkey
+  }
+  return ayRefkey(refKeyPrefix, ...args);
+}
+
+/**
+ * Creates a refkey for a declaration by combining the provided refkey with an internal
+ * refkey generated from the provided arguments.
+ *
+ * @param refkey The refkey provided by the user to be passed as is.
+ * @param args The parameters of the refkey.
+ * @returns An array of refkeys that can be passed to an Alloy declaration.
+ */
+export function declarationRefkeys(refkey?: Refkey | Refkey[], ...args: unknown[]): Refkey[] {
+  if (refkey) {
+    return [refkey, efRefkey(...args)].flat();
+  }
+  return [efRefkey(...args)];
+}

package/src/python/utils/type.ts

@@ -0,0 +1,31 @@
+import type { Typekit } from "@typespec/compiler/typekit";
+
+/**
+ * Check if a type is a literal type (string, numeric, boolean, or union variant).
+ * This is useful for determining if a type can be used in a Python Literal[] type.
+ *
+ * @param $ - The Typekit instance
+ * @param type - The type to check
+ * @returns true if the type is a literal type
+ */
+export function isLiteral($: Typekit, type: any): boolean {
+  if (!type) return false;
+
+  return (
+    $.literal.isString(type) ||
+    $.literal.isNumeric(type) ||
+    $.literal.isBoolean(type) ||
+    type.kind === "UnionVariant"
+  );
+}
+
+/**
+ * Check if all types in an array are literal types.
+ *
+ * @param $ - The Typekit instance
+ * @param types - Array of types to check
+ * @returns true if all types are literals
+ */
+export function areAllLiterals($: Typekit, types: any[]): boolean {
+  return types.every((type) => isLiteral($, type));
+}