@typespec/http-client-python 0.36.0 → 0.37.1

package/emitter/src/external-process.ts

@@ -3,8 +3,8 @@ import type { ChildProcess, SpawnOptions } from "child_process";
 import { spawn } from "child_process";
 import { randomUUID } from "crypto";
 import { mkdir, writeFile } from "fs/promises";
-import jsyaml from "js-yaml";
 import os from "os";
+import { dumpCodeModelToYaml } from "./yaml-utils.js";
 
 const tspCodeGenTempDir = joinPaths(os.tmpdir(), "tsp-codegen");
 
@@ -12,23 +12,6 @@ export function createTempPath(extension: string, prefix: string = "") {
   return joinPaths(tspCodeGenTempDir, prefix + randomUUID() + extension);
 }
 
-/**
- * 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.
- * @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: '"' });
-}
-
 /**
  * Save the given codemodel in a yaml file.
  * @param name Name of the codemodel. To give a guide to the temp file name.

package/emitter/src/http.ts

@@ -18,6 +18,7 @@ import type {
   SdkQueryParameter,
   SdkServiceMethod,
   SdkServiceResponseHeader,
+  SdkSseEventMetadata,
   SdkType,
 } from "@azure-tools/typespec-client-generator-core";
 import { getHttpOperationParameter, UsageFlags } from "@azure-tools/typespec-client-generator-core";
@@ -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/lib.ts

@@ -180,10 +180,10 @@ const libDef = {
       },
     },
     "no-sdk-clients": {
-      severity: "error",
+      severity: "warning",
       messages: {
         default:
-          "The Python emitter did not find any SDK clients in this TypeSpec program. The current Python generator expects at least one client/service to generate code.",
+          "The Python emitter did not find any SDK clients in this TypeSpec program. No client code will be generated (models can still be emitted). Suppress this warning if this is expected.",
       },
     },
     "browser-runtime-load-failed": {

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: '"' });
+}