fastapi-streams 0.0.1__py3-none-any.whl

fastapi_streams/codegen/templates/errors.ts

@@ -0,0 +1,26 @@
+// Generated by fastapi-streams. Do not edit.
+
+export class TransportError extends Error {
+  override readonly name: string = "TransportError";
+}
+
+export class HttpError<T = unknown> extends TransportError {
+  override readonly name: string = "HttpError";
+
+  constructor(
+    readonly status: number,
+    readonly details: T,
+    readonly response: Response,
+    options?: ErrorOptions,
+  ) {
+    super(`HTTP ${status} ${response.statusText}`.trim(), options);
+  }
+}
+
+export class StreamParseError extends TransportError {
+  override readonly name: string = "StreamParseError";
+
+  constructor(readonly data: string, cause: unknown) {
+    super("Invalid JSON in SSE data", { cause });
+  }
+}

fastapi_streams/codegen/templates/python/api.py.j2

@@ -0,0 +1,52 @@
+# Generated by fastapi-streams. Do not edit.
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+from pydantic import TypeAdapter
+
+from .. import models as Models
+from ..runtime import {{ runtime_imports | join(', ') }}
+
+
+class {{ class_name }}:
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+{% for operation in operations %}
+
+    def {{ operation.operation_id | snake }}(
+        self,
+        *,
+{% for parameter in operation.parameters %}
+        {{ parameter.name | snake }}: {{ parameter.type | py_type }}{{ ' | None = None' if not parameter.required else '' }},
+{% endfor %}
+{% if operation.body %}
+        body: {{ operation.body.type | py_type }}{{ ' | None = None' if not operation.body.required else '' }},
+{% endif %}
+        options: RequestOptions | None = None,
+    ) -> AsyncGenerator[{{ operation.event | py_type }}, None]:
+        query: list[tuple[str, str]] = []
+        headers: dict[str, str] = {}
+{% for parameter in operation.parameters %}
+{% if parameter.location == 'query' %}
+        append_query(query, {{ parameter.name | repr }}, {{ parameter.name | snake }}, explode={{ parameter.explode }}{{ ', required=True' if parameter.required else '' }})
+{% elif parameter.location == 'header' %}
+        set_header(headers, {{ parameter.name | repr }}, {{ parameter.name | snake }}{{ ', required=True' if parameter.required else '' }})
+{% endif %}
+{% endfor %}
+{% if operation.body %}
+        adapter = TypeAdapter({{ operation.body.type | py_type }})
+        content = adapter.dump_json(adapter.validate_python(body), by_alias=True, exclude_unset=True){{ ' if body is not None else None' if not operation.body.required else '' }}
+{% endif %}
+        return self._transport.stream(
+            {{ operation | py_path }},
+            {{ operation.method | repr }},
+            TypeAdapter({{ operation.event | py_type }}),
+            query=query,
+            headers=headers,
+{% if operation.body %}
+            body=content,
+{% endif %}
+            options=options,
+        )
+{% endfor %}

fastapi_streams/codegen/templates/python/client.py.j2

@@ -0,0 +1,40 @@
+# Generated by fastapi-streams. Do not edit.
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import TracebackType
+
+{{ http_import }}
+
+from .runtime import Transport
+{% for group in groups %}
+from .{{ group.directory }}.api import {{ group.class_name }}
+{% endfor %}
+
+
+class Client:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._transport = Transport(base_url, headers=headers, http_client=http_client)
+{% for group in groups %}
+        self.{{ group.name }} = {{ group.class_name }}(self._transport)
+{% endfor %}
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> Client:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()

fastapi_streams/codegen/templates/python/runtime.py

@@ -0,0 +1,217 @@
+# Generated by fastapi-streams. Do not edit.
+from __future__ import annotations
+
+import codecs
+from collections.abc import AsyncGenerator, Mapping, Sequence
+from dataclasses import dataclass
+from enum import Enum
+
+import httpx
+from pydantic import JsonValue, TypeAdapter, ValidationError
+
+
+class TransportError(Exception):
+    pass
+
+
+class HttpError(TransportError):
+    def __init__(self, response: httpx.Response, details: JsonValue) -> None:
+        self.status = response.status_code
+        self.response = response
+        self.details = details
+        super().__init__(f"HTTP {self.status} {response.reason_phrase}")
+
+
+class StreamParseError(TransportError):
+    def __init__(self, data: str) -> None:
+        self.data = data
+        super().__init__("Invalid JSON or event schema in SSE data")
+
+
+class _Default(Enum):
+    TIMEOUT = "inherit"
+
+
+@dataclass(frozen=True)
+class RequestOptions:
+    headers: Mapping[str, str] | None = None
+    timeout: float | None | _Default = _Default.TIMEOUT
+
+
+type ParameterValue = str | int | float | bool | None
+
+
+def encode_path(value: str | int | float | bool | None) -> str:
+    from urllib.parse import quote
+
+    text = scalar(value)
+    if text in {".", ".."}:
+        raise ValueError("Path parameters cannot be dot segments")
+    return quote(text, safe="")
+
+
+def scalar(value: str | int | float | bool | None) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def append_query(
+    query: list[tuple[str, str]],
+    name: str,
+    value: ParameterValue | Sequence[ParameterValue],
+    *,
+    explode: bool,
+    required: bool = False,
+) -> None:
+    if value is None:
+        if required:
+            raise TypeError(f"Required query parameter {name} cannot be None")
+        return
+    if not isinstance(value, str | int | float | bool):
+        if explode:
+            query.extend((name, scalar(item)) for item in value)
+        else:
+            query.append((name, ",".join(scalar(item) for item in value)))
+    else:
+        query.append((name, scalar(value)))
+
+
+def set_header(
+    headers: dict[str, str], name: str, value: ParameterValue, *, required: bool = False
+) -> None:
+    if value is None:
+        if required:
+            raise TypeError(f"Required header parameter {name} cannot be None")
+        return
+    headers[name] = scalar(value)
+
+
+async def iter_sse(response: httpx.Response) -> AsyncGenerator[str, None]:
+    decoder = codecs.getincrementaldecoder("utf-8-sig")("strict")
+    line = ""
+    data: list[str] = []
+    skip_lf = False
+
+    def accept_line() -> str | None:
+        nonlocal line, data
+        current, line = line, ""
+        if not current:
+            if not data:
+                return None
+            payload, data = "\n".join(data), []
+            return payload
+        field, _, value = current.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+        if field == "data":
+            data.append(value)
+        return None
+
+    async for chunk in response.aiter_bytes():
+        for char in decoder.decode(chunk):
+            if skip_lf:
+                skip_lf = False
+                if char == "\n":
+                    continue
+            if char in "\r\n":
+                skip_lf = char == "\r"
+                payload = accept_line()
+                if payload is not None:
+                    yield payload
+            else:
+                line += char
+    line += decoder.decode(b"", final=True)
+    if line:
+        accept_line()
+    if data:
+        yield "\n".join(data)
+
+
+class Transport:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.headers = httpx.Headers(headers)
+        self.http_client = http_client or httpx.AsyncClient(timeout=None)
+        self.owns_client = http_client is None
+
+    async def aclose(self) -> None:
+        if self.owns_client:
+            await self.http_client.aclose()
+
+    async def stream[T](
+        self,
+        path: str,
+        method: str,
+        adapter: TypeAdapter[T],
+        *,
+        query: list[tuple[str, str]],
+        headers: Mapping[str, str],
+        body: bytes | None = None,
+        options: RequestOptions | None = None,
+    ) -> AsyncGenerator[T, None]:
+        request_headers = self.headers.copy()
+        request_headers.update(headers)
+        if options and options.headers:
+            request_headers.update(options.headers)
+        request_headers["Accept"] = "text/event-stream"
+        if body is not None:
+            request_headers["Content-Type"] = "application/json"
+        try:
+            async with self.http_client.stream(
+                method,
+                self.base_url + path,
+                params=tuple(query),
+                headers=request_headers,
+                content=body,
+                timeout=options.timeout
+                if options and not isinstance(options.timeout, _Default)
+                else httpx.USE_CLIENT_DEFAULT,
+            ) as response:
+                if not response.is_success:
+                    raw = bytearray()
+                    failure: httpx.HTTPError | None = None
+                    try:
+                        async for chunk in response.aiter_bytes():
+                            raw.extend(chunk[: 65536 - len(raw)])
+                            if len(raw) >= 65536:
+                                break
+                    except httpx.HTTPError as exc:
+                        failure = exc
+                    text = raw.decode("utf-8", errors="replace")
+                    try:
+                        details = (
+                            TypeAdapter[JsonValue](JsonValue).validate_json(text)
+                            if text
+                            else None
+                        )
+                    except ValidationError:
+                        details = text
+                    raise HttpError(response, details) from failure
+                media = (
+                    response.headers.get("content-type", "")
+                    .split(";", 1)[0]
+                    .strip()
+                    .lower()
+                )
+                if media != "text/event-stream":
+                    raise TransportError(
+                        f"Expected text/event-stream, received {media!r}"
+                    )
+                async for payload in iter_sse(response):
+                    try:
+                        yield adapter.validate_json(payload)
+                    except ValidationError as exc:
+                        raise StreamParseError(payload) from exc
+        except httpx.HTTPError as exc:
+            raise TransportError("SSE HTTP transport failed") from exc
+        except UnicodeDecodeError as exc:
+            raise TransportError("Invalid UTF-8 in SSE stream") from exc

fastapi_streams/codegen/templates/sse.ts

@@ -0,0 +1,264 @@
+// Generated by fastapi-streams. Do not edit.
+import { HttpError, StreamParseError, TransportError } from "./errors.js";
+
+export interface ClientOptions {
+  baseUrl: string;
+  headers?: HeadersInit;
+  fetch?: typeof globalThis.fetch;
+  credentials?: RequestCredentials;
+}
+
+export interface RequestOptions {
+  headers?: HeadersInit;
+  signal?: AbortSignal;
+}
+
+export interface StreamRequest {
+  path: string;
+  method: string;
+  query?: URLSearchParams;
+  headers?: HeadersInit;
+  body?: string;
+}
+
+export function encodePath(value: string | number | boolean | null): string {
+  const text = String(value);
+  if (text === "." || text === "..") {
+    throw new TypeError("Path parameters cannot be dot segments");
+  }
+  return encodeURIComponent(text);
+}
+
+export function appendQuery(
+  query: URLSearchParams,
+  name: string,
+  value: string | number | boolean | null | readonly (string | number | boolean | null)[] | undefined,
+  explode: boolean,
+  required = false,
+): void {
+  if (value === undefined || value === null) {
+    if (required) throw new TypeError(`Required query parameter ${name} cannot be null or undefined`);
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (explode) {
+      for (const item of value) query.append(name, String(item));
+    } else {
+      query.append(name, value.map(String).join(","));
+    }
+  } else {
+    query.append(name, String(value));
+  }
+}
+
+export function setHeader(
+  headers: Headers,
+  name: string,
+  value: string | number | boolean | null | undefined,
+  required = false,
+): void {
+  if (value === undefined || value === null) {
+    if (required) throw new TypeError(`Required header parameter ${name} cannot be null or undefined`);
+    return;
+  }
+  headers.set(name, String(value));
+}
+
+async function readChunk(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  signal?: AbortSignal,
+): Promise<ReadableStreamReadResult<Uint8Array>> {
+  signal?.throwIfAborted();
+  if (!signal) return reader.read();
+  let onAbort: () => void = () => {};
+  const aborted = new Promise<never>((_resolve, reject) => {
+    onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([reader.read(), aborted]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+
+export async function* parseSSE<T>(
+  body: ReadableStream<Uint8Array>,
+  signal?: AbortSignal,
+): AsyncGenerator<T, void, unknown> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let line = "";
+  let data: string[] = [];
+  let skipLF = false;
+  let ended = false;
+
+  function acceptLine(): string | undefined {
+    const current = line;
+    line = "";
+    if (current === "") {
+      if (data.length === 0) return undefined;
+      const payload = data.join("\n");
+      data = [];
+      return payload;
+    }
+    const colon = current.indexOf(":");
+    const field = colon < 0 ? current : current.slice(0, colon);
+    let value = colon < 0 ? "" : current.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "data") data.push(value);
+    return undefined;
+  }
+
+  function decode(payload: string): T {
+    try {
+      return JSON.parse(payload) as T;
+    } catch (cause) {
+      throw new StreamParseError(payload, cause);
+    }
+  }
+
+  try {
+    while (true) {
+      const chunk = await readChunk(reader, signal);
+      const text = chunk.done ? decoder.decode() : decoder.decode(chunk.value, { stream: true });
+      for (const char of text) {
+        if (skipLF) {
+          skipLF = false;
+          if (char === "\n") continue;
+        }
+        if (char === "\r" || char === "\n") {
+          skipLF = char === "\r";
+          const payload = acceptLine();
+          if (payload !== undefined) yield decode(payload);
+        } else {
+          line += char;
+        }
+      }
+      if (chunk.done) {
+        ended = true;
+        if (line !== "") acceptLine();
+        if (data.length > 0) yield decode(data.join("\n"));
+        return;
+      }
+    }
+  } finally {
+    try {
+      if (!ended) await reader.cancel();
+    } finally {
+      reader.releaseLock();
+    }
+  }
+}
+
+function mergeHeaders(...sources: (HeadersInit | undefined)[]): Headers {
+  const result = new Headers();
+  for (const source of sources) {
+    new Headers(source).forEach((value, name) => result.set(name, value));
+  }
+  return result;
+}
+
+async function errorDetails(response: Response, signal: AbortSignal): Promise<unknown> {
+  if (!response.body) return undefined;
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+  let ended = false;
+  try {
+    // Error bodies can be HTML proxy pages; keep diagnostics bounded to 64 KiB.
+    while (text.length < 65536) {
+      const chunk = await readChunk(reader, signal);
+      if (chunk.done) {
+        ended = true;
+        text += decoder.decode();
+        break;
+      }
+      text += decoder.decode(chunk.value, { stream: true });
+    }
+  } finally {
+    try {
+      if (!ended) await reader.cancel();
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  text = text.slice(0, 65536);
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+export async function* stream<T>(
+  client: ClientOptions,
+  request: StreamRequest,
+  options: RequestOptions = {},
+): AsyncGenerator<T, void, unknown> {
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  if (options.signal?.aborted) onAbort();
+  let response: Response | undefined;
+  let bodyHandled = false;
+  try {
+    controller.signal.throwIfAborted();
+    const base = client.baseUrl.replace(/\/+$/, "");
+    const query = request.query?.toString();
+    const url = `${base}${request.path}${query ? `?${query}` : ""}`;
+    const headers = mergeHeaders(client.headers, request.headers, options.headers);
+    headers.set("Accept", "text/event-stream");
+    if (request.body !== undefined) headers.set("Content-Type", "application/json");
+    try {
+      response = await (client.fetch ?? globalThis.fetch)(url, {
+        method: request.method,
+        headers,
+        signal: controller.signal,
+        ...(request.body === undefined ? {} : { body: request.body }),
+        ...(client.credentials === undefined ? {} : { credentials: client.credentials }),
+      });
+    } catch (cause) {
+      controller.signal.throwIfAborted();
+      throw new TransportError("Failed to fetch SSE stream", { cause });
+    }
+    if (!response.ok) {
+      bodyHandled = true;
+      let details: unknown;
+      try {
+        details = await errorDetails(response, controller.signal);
+      } catch (cause) {
+        controller.signal.throwIfAborted();
+        throw new HttpError(response.status, undefined, response, { cause });
+      }
+      throw new HttpError(response.status, details, response);
+    }
+    const media = response.headers.get("Content-Type")?.split(";", 1)[0]?.trim().toLowerCase();
+    if (media !== "text/event-stream") {
+      throw new TransportError(`Expected text/event-stream, received ${media ?? "no Content-Type"}`);
+    }
+    if (!response.body) throw new TransportError("SSE response has no body");
+    bodyHandled = true;
+    try {
+      yield* parseSSE<T>(response.body, controller.signal);
+    } catch (cause) {
+      controller.signal.throwIfAborted();
+      if (cause instanceof TransportError) throw cause;
+      throw new TransportError("SSE stream read failed", { cause });
+    }
+  } finally {
+    options.signal?.removeEventListener("abort", onAbort);
+    try {
+      if (!bodyHandled && response?.body && !response.body.locked) {
+        try {
+          await response.body.cancel();
+        } catch (cause) {
+          throw new TransportError("Failed to close SSE response", { cause });
+        }
+      }
+    } finally {
+      controller.abort();
+    }
+  }
+}

fastapi_streams/codegen/templates/typescript/api.ts.j2

@@ -0,0 +1,52 @@
+// Generated by fastapi-streams. Do not edit.
+import type * as Types from "../types.js";
+import type { ClientOptions, RequestOptions } from "../transport/sse.js";
+import { {{ functions | join(', ') }} } from "../transport/sse.js";
+
+{% for operation in operations %}
+{% if operation.parameters or operation.body %}
+export interface {{ operation | input_name }} {
+{% for param in operation.parameters %}
+  {{ param.argument }}{{ '' if param.required else '?' }}: {{ param.type | ts_type('Types.') }};
+{% endfor %}
+{% if operation.body %}
+  body{{ '' if operation.body.required else '?' }}: {{ operation.body.type | ts_type('Types.') }};
+{% endif %}
+}
+{% endif %}
+{% if operation.errors %}
+export type {{ operation.operation_id | pascal }}Error = {{ operation | error_type }};
+{% endif %}
+
+{% endfor %}
+export function {{ factory }}(client: ClientOptions) {
+  return {
+{% for operation in operations %}
+    {{ operation.name }}(
+{% if operation.parameters or operation.body %}
+      input: {{ operation | input_name }}{{ '' if operation | required else ' = {}' }},
+{% endif %}
+      options: RequestOptions = {},
+    ): AsyncIterable<{{ operation.event | ts_type('Types.') }}> {
+      const query = new URLSearchParams();
+      const headers = new Headers();
+{% for param in operation.parameters %}
+{% if param.location == 'query' %}
+      appendQuery(query, {{ param.name | json }}, input.{{ param.argument }}, {{ 'true' if param.explode else 'false' }}{{ ', true' if param.required else '' }});
+{% elif param.location == 'header' %}
+      setHeader(headers, {{ param.name | json }}, input.{{ param.argument }}{{ ', true' if param.required else '' }});
+{% endif %}
+{% endfor %}
+      return stream<{{ operation.event | ts_type('Types.') }}>(client, {
+        path: {{ operation | path }},
+        method: {{ operation.method | json }},
+        query,
+        headers,
+{% if operation.body %}
+        ...(input.body === undefined ? {} : { body: JSON.stringify(input.body) }),
+{% endif %}
+      }, options);
+    },
+{% endfor %}
+  };
+}

fastapi_streams/codegen/templates/typescript/client.ts.j2

@@ -0,0 +1,15 @@
+// Generated by fastapi-streams. Do not edit.
+import type { ClientOptions } from "./transport/sse.js";
+{% for group in groups %}
+import { {{ group.factory }} } from "./{{ group.directory }}/api.js";
+{% endfor %}
+
+export function createClient(options: ClientOptions) {
+  return {
+{% for group in groups %}
+    {{ group.name }}: {{ group.factory }}(options),
+{% endfor %}
+  };
+}
+
+export type Client = ReturnType<typeof createClient>;

fastapi_streams/codegen/templating.py

@@ -0,0 +1,19 @@
+from collections.abc import Callable
+from typing import Any, cast
+
+from jinja2 import Environment, PackageLoader, StrictUndefined
+
+
+def environment() -> Environment:
+    return Environment(
+        loader=PackageLoader("fastapi_streams.codegen", "templates"),
+        undefined=StrictUndefined,
+        autoescape=False,
+        keep_trailing_newline=True,
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+
+
+def add_filters(env: Environment, **filters: Callable[..., Any]) -> None:
+    cast(dict[str, Callable[..., Any]], env.filters).update(filters)