@typespec/http-client-python 0.35.1 → 0.37.0

package/emitter/src/http.ts

@@ -1,7 +1,6 @@
 import { getNamespaceFullName, NoTarget } from "@typespec/compiler";
 
-import {
-  getHttpOperationParameter,
+import type {
   SdkBasicServiceMethod,
   SdkBodyParameter,
   SdkClientType,
@@ -19,11 +18,13 @@ import {
   SdkQueryParameter,
   SdkServiceMethod,
   SdkServiceResponseHeader,
+  SdkSseEventMetadata,
   SdkType,
-  UsageFlags,
 } from "@azure-tools/typespec-client-generator-core";
-import { HttpStatusCodeRange } from "@typespec/http";
-import { PythonSdkContext, reportDiagnostic } from "./lib.js";
+import { getHttpOperationParameter, UsageFlags } from "@azure-tools/typespec-client-generator-core";
+import type { HttpStatusCodeRange } from "@typespec/http";
+import type { PythonSdkContext } from "./lib.js";
+import { reportDiagnostic } from "./lib.js";
 import { getType, KnownTypes } from "./types.js";
 import {
   emitParamBase,
@@ -42,6 +43,158 @@ export enum ReferredByOperationTypes {
   NonPagingOnly = 2,
 }
 
+type StructuredStreamKind = "jsonl" | "sse";
+type EmittedType = ReturnType<typeof getType>;
+
+interface StructuredStreamEvent {
+  eventType: string | undefined;
+  /**
+   * Payload type for this one SSE event. For an event envelope, this is the type of the property
+   * marked `@Events.data`. Together with {@link eventType} these form the
+   * runtime dispatch table (wire event name -> model to deserialize) inside the generated
+   * `_callback`. This is a narrower type than {@link StructuredStreamingInfo.itemType}.
+   */
+  payloadType: EmittedType;
+  /**
+   * True when this event is a `@terminalEvent` that carries a payload (a named / model event,
+   * not a bare string-constant sentinel). Such events are deserialized and yielded like any
+   * other event, and iteration stops immediately after one is yielded. Contrast with
+   * {@link StructuredStreamingInfo.terminalEvent}, the sentinel that stops without yielding.
+   */
+  isTerminal?: boolean;
+  /** Content type of the payload, not the enclosing event. */
+  payloadContentType?: string;
+}
+
+interface StructuredStreamingInfo {
+  kind: StructuredStreamKind;
+  /**
+   * The aggregate stream element type used for the `Stream[T]` / `AsyncStream[T]` return
+   * annotation (a single type expression). For homogeneous JSONL this is the one model; for
+   * heterogeneous SSE this is the union of every event payload.
+   *
+   * Note the deliberate overlap with the per-event {@link StructuredStreamEvent.payloadType}: for
+   * heterogeneous SSE this union is exactly the sum of the `events[]` payload types. Both are
+   * carried because the union alone cannot recover the wire-name -> member mapping needed for
+   * dispatch, and the events list alone is not a single valid type expression for the annotation.
+   */
+  itemType: EmittedType;
+  events?: StructuredStreamEvent[];
+  /**
+   * A bare string-constant `@terminalEvent` with no event name (e.g. `"[DONE]"`). Iteration
+   * stops when an event's `data` equals this value, and the sentinel is NOT yielded. Named /
+   * model terminal events are carried in {@link events} with `isTerminal: true` instead.
+   */
+  terminalEvent?: string;
+}
+
+/** Whether pygen can deserialize the stream item type. */
+export function isStructuredStreamType(type: SdkType): boolean {
+  switch (type.kind) {
+    case "model":
+    case "union":
+      return true;
+    case "nullable":
+      return isStructuredStreamType(type.type);
+    default:
+      return false;
+  }
+}
+
+export function getStructuredStreamKind(
+  response: SdkHttpResponse | SdkHttpErrorResponse,
+): StructuredStreamKind | undefined {
+  if (response.sseMetadata) return "sse";
+
+  const contentTypes = response.streamMetadata?.contentTypes ?? response.contentTypes ?? [];
+  for (const contentType of contentTypes) {
+    const mediaType = contentType.split(";", 1)[0].trim().toLowerCase();
+    if (mediaType === "text/event-stream") return "sse";
+    if (mediaType === "application/jsonl") return "jsonl";
+  }
+  return undefined;
+}
+
+function getStringConstantValue(type: SdkType): string | undefined {
+  if (type.kind === "nullable") return getStringConstantValue(type.type);
+  return type.kind === "constant" && typeof type.value === "string" ? type.value : undefined;
+}
+
+/**
+ * Split the SSE events into the runtime dispatch table and a bare string-constant sentinel.
+ *
+ * A `@terminalEvent` comes in two shapes:
+ *   * a nameless string constant (e.g. `"[DONE]"`) -> a pure sentinel: iteration stops when an
+ *     event's `data` equals this value and the event is NOT yielded. Returned as `terminalEvent`.
+ *   * a named / model event (e.g. `error`, `response.completed`) -> carries a payload the consumer
+ *     needs, so it is deserialized and yielded like any other event, then iteration stops. Returned
+ *     in `events` with `isTerminal: true`.
+ *
+ * `toPayloadType` maps event payloads to emitted types; it is injected so this partitioning stays
+ * a pure function that can be unit-tested without a full emitter context.
+ */
+export function partitionSSEEvents(
+  events: readonly SdkSseEventMetadata[],
+  toPayloadType: (type: SdkType) => EmittedType,
+): { events: StructuredStreamEvent[]; terminalEvent?: string } {
+  const dispatch: StructuredStreamEvent[] = [];
+  let terminalEvent: string | undefined;
+  for (const event of events) {
+    if (event.isTerminalEvent) {
+      const sentinelValue =
+        event.eventType === undefined
+          ? (getStringConstantValue(event.payloadType) ?? getStringConstantValue(event.type))
+          : undefined;
+      if (sentinelValue !== undefined) {
+        // Keep the first sentinel; no current spec defines more than one.
+        terminalEvent ??= sentinelValue;
+        continue;
+      }
+      dispatch.push({
+        eventType: event.eventType,
+        payloadType: toPayloadType(event.payloadType),
+        isTerminal: true,
+        payloadContentType: event.payloadContentType,
+      });
+      continue;
+    }
+    dispatch.push({
+      eventType: event.eventType,
+      payloadType: toPayloadType(event.payloadType),
+      payloadContentType: event.payloadContentType,
+    });
+  }
+  return terminalEvent !== undefined ? { events: dispatch, terminalEvent } : { events: dispatch };
+}
+
+function emitStructuredStreamingInfo(
+  context: PythonSdkContext,
+  response: SdkHttpResponse | SdkHttpErrorResponse,
+): StructuredStreamingInfo | undefined {
+  const streamMetadata = response.streamMetadata;
+  if (!streamMetadata || !isStructuredStreamType(streamMetadata.streamType)) return undefined;
+
+  const kind = getStructuredStreamKind(response);
+  if (!kind) return undefined;
+
+  const streaming: StructuredStreamingInfo = {
+    kind,
+    itemType: getType(context, streamMetadata.streamType),
+  };
+  if (kind !== "sse") return streaming;
+
+  const sseMetadata = response.sseMetadata;
+  if (!sseMetadata || sseMetadata.events.length === 0) return undefined;
+
+  const { events, terminalEvent } = partitionSSEEvents(sseMetadata.events, (type) =>
+    getType(context, type),
+  );
+  if (events.length > 0) streaming.events = events;
+  if (terminalEvent !== undefined) streaming.terminalEvent = terminalEvent;
+
+  return streaming;
+}
+
 function isEtagType(type: SdkType): boolean {
   if (type.kind === "nullable") return isEtagType(type.type);
   const raw = type.__raw;
@@ -682,6 +835,7 @@ function emitHttpResponse(
       "invalid-lro-result",
       method,
     ),
+    streaming: isException ? undefined : emitStructuredStreamingInfo(context, response),
   };
 }
 

package/emitter/src/index.ts

@@ -1,2 +1,3 @@
 export * from "./emitter.js";
-export { $lib, PythonEmitterOptions, PythonEmitterOptionsSchema } from "./lib.js";
+export { $lib, PythonEmitterOptionsSchema } from "./lib.js";
+export type { PythonEmitterOptions } from "./lib.js";

package/emitter/src/lib.ts

@@ -1,9 +1,7 @@
-import {
-  SdkContext,
-  SdkType,
-  UnbrandedSdkEmitterOptions,
-} from "@azure-tools/typespec-client-generator-core";
-import { createTypeSpecLibrary, JSONSchemaType, paramMessage } from "@typespec/compiler";
+import type { SdkContext, SdkType } from "@azure-tools/typespec-client-generator-core";
+import { UnbrandedSdkEmitterOptions } from "@azure-tools/typespec-client-generator-core";
+import type { JSONSchemaType } from "@typespec/compiler";
+import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
 
 export interface PythonEmitterOptions {
   "api-version"?: string;
@@ -24,6 +22,7 @@ export interface PythonEmitterOptions {
   "head-as-boolean"?: boolean;
   "use-pyodide"?: boolean;
   "keep-setup-py"?: boolean;
+  "generate-typeddict"?: boolean;
   "keep-pyproject-fields"?: {
     authors?: boolean;
     description?: boolean;
@@ -111,6 +110,12 @@ export const PythonEmitterOptionsSchema: JSONSchemaType<PythonEmitterOptions> =
       description:
         "Whether to keep the existing `setup.py` when `generate-packaging-files` is `true`. If set to `false` and by default, `pyproject.toml` will be generated instead. To generate `setup.py`, use `basic-setup-py`.",
     },
+    "generate-typeddict": {
+      type: "boolean",
+      nullable: true,
+      description:
+        "Whether to add TypedDict typing for JSON dictionary input in `models-mode: dpg`, instead of accepting only generic JSON. This enriches the typing on the existing overloads rather than adding another request-body overload. Defaults to `true`.",
+    },
     "keep-pyproject-fields": {
       type: "object",
       nullable: true,

package/emitter/src/node-runner.browser.ts

@@ -6,7 +6,8 @@
 import type { EmitContext } from "@typespec/compiler";
 import { NoTarget } from "@typespec/compiler";
 import type { PyodideInterface } from "pyodide";
-import { PythonEmitterOptions, reportDiagnostic } from "./lib.js";
+import type { PythonEmitterOptions } from "./lib.js";
+import { reportDiagnostic } from "./lib.js";
 
 export interface RunNodeEmitArgs {
   context: EmitContext<PythonEmitterOptions>;

package/emitter/src/node-runner.ts

@@ -5,16 +5,19 @@
 // `node-runner.browser.ts` stub is swapped in via the `"browser"` field in
 // `package.json` when bundling with `platform: "browser"`.
 
-import { EmitContext, NoTarget } from "@typespec/compiler";
+import type { EmitContext } from "@typespec/compiler";
+import { NoTarget } from "@typespec/compiler";
 import { execSync } from "child_process";
 import fs from "fs";
 import os from "os";
 import path, { dirname } from "path";
-import { loadPyodide, PyodideInterface } from "pyodide";
+import type { PyodideInterface } from "pyodide";
+import { loadPyodide } from "pyodide";
 import { fileURLToPath } from "url";
 import { blackExcludeDirs, PYGEN_WHEEL_FILENAME } from "./constants.js";
 import { saveCodeModelAsYaml } from "./external-process.js";
-import { PythonEmitterOptions, reportDiagnostic } from "./lib.js";
+import type { PythonEmitterOptions } from "./lib.js";
+import { reportDiagnostic } from "./lib.js";
 import { runPython3 } from "./run-python3.js";
 import { quoteShellArg } from "./utils.js";
 

package/emitter/src/system-requirements.ts

@@ -1,4 +1,5 @@
-import { ChildProcess, spawn, SpawnOptions } from "child_process";
+import type { ChildProcess, SpawnOptions } from "child_process";
+import { spawn } from "child_process";
 import { coerce, satisfies } from "semver";
 
 /*

package/emitter/src/types.ts

@@ -1,5 +1,4 @@
-import {
-  isHttpMetadata,
+import type {
   SdkArrayType,
   SdkBuiltInType,
   SdkConstantType,
@@ -14,12 +13,14 @@ import {
   SdkModelType,
   SdkType,
   SdkUnionType,
-  UsageFlags,
 } from "@azure-tools/typespec-client-generator-core";
-import { getEncode, Type } from "@typespec/compiler";
-import { HttpAuth, Visibility } from "@typespec/http";
+import { isHttpMetadata, UsageFlags } from "@azure-tools/typespec-client-generator-core";
+import type { Type } from "@typespec/compiler";
+import { getEncode } from "@typespec/compiler";
+import type { HttpAuth } from "@typespec/http";
+import { Visibility } from "@typespec/http";
 import { dump } from "js-yaml";
-import { PythonSdkContext } from "./lib.js";
+import type { PythonSdkContext } from "./lib.js";
 import {
   camelToSnakeCase,
   emitParamBase,
@@ -473,10 +474,17 @@ const sdkScalarKindToPythonKind: Record<string, string> = {
   azureLocation: "string",
 };
 
+const supportedPythonEncodings = new Map<string, ReadonlySet<string>>([
+  ["boolean", new Set(["string"])],
+  ["integer", new Set(["string"])],
+  ["bytes", new Set(["base64", "base64url"])],
+]);
+
 function emitBuiltInType(
   context: PythonSdkContext,
   type: SdkBuiltInType | SdkDurationType | SdkDateTimeType,
 ): Record<string, any> {
+  const pythonType = sdkScalarKindToPythonKind[type.kind] || type.kind;
   if (type.encode) {
     if (type.kind === "duration") {
       if (type.encode === "ISO8601") {
@@ -508,7 +516,14 @@ function emitBuiltInType(
       }
     }
 
-    // fallback to wire type for unknown or unsupported encode
+    if (supportedPythonEncodings.get(pythonType)?.has(type.encode)) {
+      return getSimpleTypeResult(context, {
+        type: pythonType,
+        encode: type.encode,
+      });
+    }
+
+    // Python cannot apply unknown/custom encodings, so expose the wire type instead of silently ignoring the encoding.
     if ("wireType" in type && type.wireType !== undefined) {
       return getSimpleTypeResult(context, {
         type: sdkScalarKindToPythonKind[type.wireType.kind] || type.wireType.kind,
@@ -518,7 +533,7 @@ function emitBuiltInType(
   }
 
   return getSimpleTypeResult(context, {
-    type: sdkScalarKindToPythonKind[type.kind] || type.kind, // TODO: switch to kind
+    type: pythonType,
     encode: type.encode,
   });
 }

package/emitter/src/utils.ts

@@ -1,5 +1,4 @@
-import {
-  InitializedByFlags,
+import type {
   SdkCredentialParameter,
   SdkEndpointParameter,
   SdkHeaderParameter,
@@ -13,9 +12,11 @@ import {
   SdkServiceResponseHeader,
   SdkType,
 } from "@azure-tools/typespec-client-generator-core";
+import { InitializedByFlags } from "@azure-tools/typespec-client-generator-core";
 import { getNamespaceFullName } from "@typespec/compiler";
-import { marked, Token } from "marked";
-import { PythonSdkContext } from "./lib.js";
+import type { Token } from "marked";
+import { marked } from "marked";
+import type { PythonSdkContext } from "./lib.js";
 import { getSimpleTypeResult, getType } from "./types.js";
 
 function IsFullyUpperCase(identifier: string, maxUppercasePreserve: number) {

package/emitter/src/yaml-utils.ts

@@ -0,0 +1,22 @@
+import jsyaml from "js-yaml";
+
+/**
+ * Serialize the given codemodel to a YAML string.
+ *
+ * The generated YAML is consumed by the Python generator, which parses it with
+ * PyYAML (YAML 1.1). js-yaml, on the other hand, dumps using YAML 1.2 rules, so
+ * plain scalars such as `2020_01_01` (a snake-cased enum member name) are left
+ * unquoted because YAML 1.2 does not treat underscores as integer separators.
+ * PyYAML would then read `2020_01_01` back as the integer `20200101`, corrupting
+ * string values (e.g. enum member names, descriptions). Forcing every string
+ * scalar to be quoted guarantees that PyYAML round-trips them as strings.
+ *
+ * This module must remain browser-safe (no Node built-ins): `emitter.ts` calls
+ * this function on the browser/Pyodide path, and esbuild bundles it into the
+ * playground bundle with `platform: "browser"`.
+ * @param codemodel Codemodel to serialize
+ * @return the YAML representation of the codemodel.
+ */
+export function dumpCodeModelToYaml(codemodel: unknown): string {
+  return jsyaml.dump(codemodel, { forceQuotes: true, quotingType: '"' });
+}