fastapi-streams 0.2.0__tar.gz → 0.3.0__tar.gz

{fastapi_streams-0.2.0 → fastapi_streams-0.3.0}/CHANGELOG.md

@@ -3,6 +3,51 @@
 All notable changes and consumer upgrade steps are recorded here. Entries marked
 unreleased describe prepared source versions that have not been published.
 
+## 0.3.0 - 2026-10-18
+
+### Breaking changes
+
+- Regenerated Python SDKs validate path, query and header parameters at the
+  method call, before serialization and HTTP I/O. Invalid types or supported
+  scalar constraints now raise Pydantic `ValidationError` locally. Regenerate
+  SDKs, fix rejected arguments, and catch request validation around the method
+  call rather than only around stream iteration. Request bodies retain their
+  existing validation timing; HTTP still starts when iteration begins.
+- TypeScript generation now diagnoses scalar constraints it cannot enforce.
+  Review the selected target's diagnostics before promoting warnings to errors.
+  Existing known limitations can be accepted by exact diagnostic ID with a
+  review reason; do not suppress the warning category globally.
+
+### Added
+
+- Cache generated parameter, body and event TypeAdapters. Keep valid parameter
+  encoding, integer representations of number parameters, query array explosion,
+  optional omission and JSON body aliases unchanged.
+- Source-located diagnostics include JSON Pointer, operation ID, method/path,
+  keyword/value, target and enforcement limitation. Referenced and inline schemas
+  are located in the original document, with each affected operation identified.
+- Add `--diagnostics FILE`, `--strict` and `--allow-diagnostics FILE` to generation
+  and drift checks. Reports are deterministic JSON with stable identities;
+  malformed, duplicate and stale allowances fail before generated files change.
+  Repository drift checks use strict mode with reviewed TypeScript limitations.
+- Generated Python `StreamParseError` exposes `operation_id`, `category`
+  (`invalid_json` or `invalid_event_schema`) and `validation_errors`. Structured
+  details exclude input values and validator context. Keep `.data`, exception
+  chaining and the existing constructor; raw data and chained causes can contain
+  sensitive values and are never logged automatically by the SDK.
+- Add request/diagnostic/error regression tests for both Python HTTP backends and
+  installed-wheel consumers, plus a documented validation support matrix.
+
+### Upgrade from 0.2.0
+
+1. Upgrade the generator to 0.3.0 and regenerate with your existing HTTP backend.
+2. Validate consumer call sites, including invalid requests, before adoption.
+   Ordinary Pydantic coercion applies; valid numeric serialization is preserved.
+3. Generate JSON diagnostics and review exact allowances before enabling strict
+   CI. Changed locations, constraints, values, operations or targets need review.
+4. Read stream failure categories and structured details through public fields.
+   Keep raw payloads and full exception chains out of routine logs.
+
 ## 0.2.0 - 2026-10-18
 
 - Source preparation passed workspace CI, independent wheel matrices and the

{fastapi_streams-0.2.0 → fastapi_streams-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-streams
-Version: 0.2.0
+Version: 0.3.0
 Summary: Typed FastAPI streams with generated TypeScript and Python clients.
 Project-URL: Documentation, https://github.com/mathisarends/canon/tree/main/packages/fastapi-streams/docs
 Project-URL: Source, https://github.com/mathisarends/canon/tree/main/packages/fastapi-streams

{fastapi_streams-0.2.0 → fastapi_streams-0.3.0}/docs/clients.md

@@ -121,6 +121,38 @@ remain ordinary members of the user-defined union.
 
 ## HTTP error contracts
 
+Python request parameters and JSON bodies are validated when calling the method;
+catch Pydantic `ValidationError` around that call. Network and event errors occur
+while iterating. See the [validation matrix and CI policy](codegen.md#validation-support-matrix).
+
+Generated Python `StreamParseError` provides these public fields:
+
+| Field | Meaning |
+| --- | --- |
+| `operation_id` | Source OpenAPI operation ID |
+| `category` | `invalid_json` for malformed JSON; `invalid_event_schema` for invalid event shapes/constraints |
+| `validation_errors` | Pydantic error dictionaries with `type`, `loc`, `msg`; input values, context and URLs are excluded |
+| `data` | Original SSE data payload, retained for explicit inspection |
+
+For errors raised by generated operations, category and operation ID are always
+set. The existing `StreamParseError(data)` constructor remains valid; manually
+constructed errors can have `None` provenance/category and empty details.
+The original Pydantic `ValidationError` remains chained as `__cause__`.
+
+```python
+try:
+    async for event in client.runs.run_events(run_id="run_abc"):
+        handle(event)
+except StreamParseError as error:
+    record_failure(error.operation_id, error.category, error.validation_errors)
+```
+
+The SDK does not log event payloads or exceptions automatically. Raw `.data` and
+the full chained exception may contain sensitive values; log only reviewed fields.
+Even structured messages and field names should follow the consumer's logging
+policy. Malformed known events still fail with `unknown_events="ignore"`; only
+valid JSON objects with unknown string discriminator tags can be skipped.
+
 The SDK works with ordinary OpenAPI response declarations, including
 `application/json`, `application/problem+json`, and other declared response media
 types. No error registry or particular problem envelope is required. Declare

{fastapi_streams-0.2.0 → fastapi_streams-0.3.0}/docs/codegen.md

@@ -119,6 +119,15 @@ fail explicitly.
 
 ## Runtime validation and unknown variants
 
+Python validates path, query and header parameters and JSON request bodies at the
+method call, before serialization or HTTP I/O. Invalid arguments raise Pydantic
+`ValidationError` immediately, even if the returned iterator is never consumed.
+HTTP starts when iteration begins. Optional parameters supplied as `None` are
+omitted, preserving existing omission semantics. Pydantic's normal coercion
+applies; this is not Pydantic strict mode. Valid scalar encoding, integer values
+of number parameters (`0` stays `0`), query array explosion and body aliases are
+preserved. Adapters are cached in each generated API class.
+
 Python validates generated event models and request bodies with Pydantic. Supported
 scalar constraints are `pattern`, `minLength`, `maxLength`, `minimum`, `maximum`,
 `exclusiveMinimum`, `exclusiveMaximum`, and `multipleOf`. They survive nested
@@ -150,6 +159,73 @@ unknown nested variants inside a known event fail too. The option adds no retry,
 reconnect or replay. TypeScript continues to forward JSON-decoded values without
 runtime union validation. Regenerate existing Python SDKs to obtain the option.
 
+## Validation support matrix
+
+| SDK target / boundary | Runtime shape validation | Supported scalar constraints | Timing |
+| --- | --- | --- | --- |
+| Python path/query/header | Yes | Yes, including referenced scalars and query array items | Method call, before serialization |
+| Python JSON request body | Yes | Yes, including nested values | Method call |
+| Python SSE event data | Yes | Yes, including nested values | Each event during iteration |
+| Python declared HTTP error bodies | Explicit consumer TypeAdapter | When explicitly validated | Consumer-controlled |
+| TypeScript parameters/body/events | Static types; events are JSON-decoded | No runtime enforcement | Generation diagnoses limitations |
+
+Unsupported formats and collection/object constraints remain diagnostics rather
+than implicit runtime validators. Optional `None` query/header parameters mean
+omission, not JSON null. Server-side validation remains necessary for every client.
+
+## Source diagnostics and CI policy
+
+`generate`, `generate --check` and `check` accept these options:
+
+```sh
+uv run fastapi-streams check --schema openapi.json --language python \
+  --output generated --diagnostics reports/python.json --strict \
+  --allow-diagnostics reviewed-python.json
+```
+
+Omit `--allow-diagnostics` when no limitations are accepted. The JSON report
+(`version: 1`, `diagnostics: [...]`) includes each diagnostic's `id`, `code`,
+`pointer`, `keyword`, `value`, `target`, `operation_id`, `method`, `path`, `message`
+and `accepted` status. Pointers are RFC 6901 paths into the original document,
+including inline schemas and referenced component definitions. Shared definitions
+identify each affected operation; unused components do not generate warnings.
+SSE framing metadata is outside generated event-model validation.
+
+`unsupported-constraint` identifies an unenforced rule for the selected target;
+TypeScript also diagnoses Python-supported scalar constraints because TypeScript
+has no runtime schema validator. Python's `optional-discriminator` diagnoses event
+selection risks without changing field requiredness. Human-readable warnings
+contain the same location, keyword/value, operation and limitation as the report.
+
+Without `--strict`, unaccepted diagnostics remain warnings. With it, any
+unaccepted diagnostic fails with exit code 2 before generated files change; drift
+still uses exit code 1. Reports are written even on strict-policy failure. Keep
+the report outside generated output and separate from schema/allowance inputs.
+
+Review the report and explicitly record an allowance, for example:
+
+```json
+{
+  "allow": [
+    {
+      "id": "unsupported-constraint:<copy the exact ID from the report>",
+      "reason": "Reviewed upstream UUID validation; client remains a string."
+    }
+  ]
+}
+```
+
+IDs include code, source pointer, keyword/value, target and operation context;
+message wording and schema filename are excluded. Changed constraints or contexts
+need a new review. Empty reasons, duplicate IDs, malformed files and stale
+allowances fail explicitly. Keep separate policies for each contract/target.
+Repository drift checks use strict mode with reviewed TypeScript allowances.
+
+Python generator API users can collect the same objects with
+`build_ir(document, target="python", diagnostics=items)` where `items` is an empty
+list. Omitting `diagnostics` emits warnings; the default target is Python. Select
+the matching target explicitly before calling the corresponding generator.
+
 ## Existing native streams and mixed REST generation
 
 See the [native transport and mixed-codegen recipe](native-transports.md) when

{fastapi_streams-0.2.0 → fastapi_streams-0.3.0}/examples/agent_runs/errors.py

@@ -30,7 +30,7 @@ async def consume_with_errors(client: Client, run_id: str) -> None:
         print("Unexpected HTTP response", error.status, error.details)
         raise
     except StreamParseError as error:
-        print("Invalid event data", error.data)
+        print("Invalid event data", error.operation_id, error.category)
         raise
     except TransportError as error:
         print("Stream transport failed", str(error))

{fastapi_streams-0.2.0 → fastapi_streams-0.3.0}/examples/agent_runs/generated_python/agent_runs/api.py

@@ -6,10 +6,17 @@ from collections.abc import AsyncGenerator
 from pydantic import TypeAdapter
 
 from .. import models as Models
-from ..runtime import RequestOptions, Transport, append_query, encode_path
+from ..runtime import RequestOptions, Transport, append_query, encode_path, validate_parameter as _validate_parameter
 
 
 class AgentRunsApi:
+    _stream_prompt_run_id_adapter = TypeAdapter(str)
+    _stream_prompt_body_adapter = TypeAdapter(Models.RunRequest)
+    _stream_prompt_event_adapter = TypeAdapter(Models.RunEvent)
+    _stream_run_events_run_id_adapter = TypeAdapter(str)
+    _stream_run_events_delay_adapter = TypeAdapter(Models.StreamRunEventsDelay)
+    _stream_run_events_event_adapter = TypeAdapter(Models.RunEvent)
+
     def __init__(self, transport: Transport) -> None:
         self._transport = transport
 
@@ -33,20 +40,26 @@ class AgentRunsApi:
 
         Declared HTTP response bodies: StreamPromptErrorBody (422 application/json). HttpError.details may also contain undeclared JSON, text, or no body; validate it before accessing application fields.
 
+        Path, query and header parameters and JSON bodies are validated with Pydantic at the method call, before serialization or HTTP I/O. Optional None parameters are omitted. Pydantic's normal type coercion applies; invalid arguments raise ValidationError.
+
         Use contextlib.aclosing for deterministic cleanup when exiting iteration early. Task cancellation closes the response and propagates normally.
 
         Events are validated with Pydantic against generated shapes, variants and supported scalar constraints (string pattern/length, numeric bounds/multiples). Unsupported source constraints are diagnosed during generation; this is not full JSON Schema validation.
 
         Unknown event variants fail by default. For a top-level discriminated union, RequestOptions(unknown_events='ignore') skips unknown string tags. Malformed known events, missing tags and invalid JSON still fail.
+
+        StreamParseError exposes operation_id, category (invalid_json or invalid_event_schema), and validation_errors without input values. Its data and chained cause may contain sensitive content; the SDK does not log them automatically.
         """
+        run_id = _validate_parameter(self._stream_prompt_run_id_adapter, run_id)
         query: list[tuple[str, str]] = []
         headers: dict[str, str] = {}
-        adapter = TypeAdapter(Models.RunRequest)
+        adapter = self._stream_prompt_body_adapter
         content = adapter.dump_json(adapter.validate_python(body), by_alias=True, exclude_unset=True)
         return self._transport.stream(
             '/v1/runs/' + encode_path(run_id) + '/events',
             'POST',
-            TypeAdapter(Models.RunEvent),
+            self._stream_prompt_event_adapter,
+            operation_id='stream_prompt',
             query=query,
             headers=headers,
             body=content,
@@ -73,19 +86,27 @@ class AgentRunsApi:
 
         Declared HTTP response bodies: StreamRunEventsErrorBody (422 application/json). HttpError.details may also contain undeclared JSON, text, or no body; validate it before accessing application fields.
 
+        Path, query and header parameters and JSON bodies are validated with Pydantic at the method call, before serialization or HTTP I/O. Optional None parameters are omitted. Pydantic's normal type coercion applies; invalid arguments raise ValidationError.
+
         Use contextlib.aclosing for deterministic cleanup when exiting iteration early. Task cancellation closes the response and propagates normally.
 
         Events are validated with Pydantic against generated shapes, variants and supported scalar constraints (string pattern/length, numeric bounds/multiples). Unsupported source constraints are diagnosed during generation; this is not full JSON Schema validation.
 
         Unknown event variants fail by default. For a top-level discriminated union, RequestOptions(unknown_events='ignore') skips unknown string tags. Malformed known events, missing tags and invalid JSON still fail.
+
+        StreamParseError exposes operation_id, category (invalid_json or invalid_event_schema), and validation_errors without input values. Its data and chained cause may contain sensitive content; the SDK does not log them automatically.
         """
+        run_id = _validate_parameter(self._stream_run_events_run_id_adapter, run_id)
+        if delay is not None:
+            delay = _validate_parameter(self._stream_run_events_delay_adapter, delay)
         query: list[tuple[str, str]] = []
         headers: dict[str, str] = {}
         append_query(query, 'delay', delay, explode=True)
         return self._transport.stream(
             '/v1/runs/' + encode_path(run_id) + '/events',
             'GET',
-            TypeAdapter(Models.RunEvent),
+            self._stream_run_events_event_adapter,
+            operation_id='stream_run_events',
             query=query,
             headers=headers,
             options=options,

{fastapi_streams-0.2.0/tests/fixtures → fastapi_streams-0.3.0/examples/agent_runs}/generated_python/runtime.py

@@ -5,10 +5,11 @@ import codecs
 from collections.abc import AsyncGenerator, Mapping, Sequence
 from dataclasses import dataclass
 from enum import Enum
-from typing import Literal
+from typing import Literal, cast
 
 import httpx
 from pydantic import JsonValue, TypeAdapter, ValidationError
+from pydantic_core import ErrorDetails
 
 
 class TransportError(Exception):
@@ -24,8 +25,20 @@ class HttpError(TransportError):
 
 
 class StreamParseError(TransportError):
-    def __init__(self, data: str) -> None:
+    """Invalid event data. Raw data and chained exceptions may contain secrets."""
+
+    def __init__(
+        self,
+        data: str,
+        *,
+        operation_id: str | None = None,
+        category: Literal["invalid_json", "invalid_event_schema"] | None = None,
+        validation_errors: list[ErrorDetails] | None = None,
+    ) -> None:
         self.data = data
+        self.operation_id = operation_id
+        self.category = category
+        self.validation_errors = validation_errors or []
         super().__init__("Invalid JSON or event schema in SSE data")
 
 
@@ -43,6 +56,11 @@ class RequestOptions:
 type ParameterValue = str | int | float | bool | None
 
 
+def validate_parameter[T](adapter: TypeAdapter[T], value: T) -> T:
+    """Validate/coerce inputs while preserving valid numeric wire representations."""
+    return _preserve_numbers(value, adapter.validate_python(value))
+
+
 def encode_path(value: str | int | float | bool | None) -> str:
     from urllib.parse import quote
 
@@ -155,6 +173,7 @@ class Transport:
         method: str,
         adapter: TypeAdapter[T],
         *,
+        operation_id: str | None = None,
         query: list[tuple[str, str]],
         headers: Mapping[str, str],
         body: bytes | None = None,
@@ -226,19 +245,62 @@ class Transport:
                     try:
                         yield adapter.validate_json(payload)
                     except ValidationError as exc:
+                        # Exclude input and arbitrary validator context from public
+                        # diagnostics. The original cause remains available explicitly.
+                        details = exc.errors(
+                            include_input=False,
+                            include_context=False,
+                            include_url=False,
+                        )
+                        category: Literal["invalid_json", "invalid_event_schema"] = (
+                            "invalid_json"
+                            if any(error["type"] == "json_invalid" for error in details)
+                            else "invalid_event_schema"
+                        )
                         if discriminator is not None:
                             try:
                                 value = TypeAdapter[JsonValue](JsonValue).validate_json(
                                     payload
                                 )
                             except ValidationError:
-                                raise StreamParseError(payload) from exc
+                                raise StreamParseError(
+                                    payload,
+                                    operation_id=operation_id,
+                                    category="invalid_json",
+                                    validation_errors=details,
+                                ) from exc
                             if isinstance(value, dict):
                                 tag = value.get(discriminator)
                                 if isinstance(tag, str) and tag not in known_tags:
                                     continue
-                        raise StreamParseError(payload) from exc
+                        raise StreamParseError(
+                            payload,
+                            operation_id=operation_id,
+                            category=category,
+                            validation_errors=details,
+                        ) 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
+
+
+def _preserve_numbers[T](original: object, validated: T) -> T:
+    if (
+        type(original) is int
+        and isinstance(validated, float)
+        and validated.is_integer()
+        and original == int(validated)
+    ):
+        return cast(T, original)
+    if isinstance(original, list | tuple) and isinstance(validated, list):
+        before = cast(Sequence[object], original)
+        after = cast(list[object], validated)
+        return cast(
+            T,
+            [
+                _preserve_numbers(old, new)
+                for old, new in zip(before, after, strict=True)
+            ],
+        )
+    return validated

{fastapi_streams-0.2.0 → fastapi_streams-0.3.0}/fastapi_streams/__init__.py

@@ -1,4 +1,4 @@
 from fastapi_streams.router import StreamRouter
 
 __all__ = ["StreamRouter"]
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{fastapi_streams-0.2.0 → fastapi_streams-0.3.0}/fastapi_streams/codegen/cli.py

@@ -1,15 +1,20 @@
+from __future__ import annotations
+
 import argparse
 import importlib
 import json
 import sys
 from pathlib import Path
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 from fastapi import FastAPI
 
 from fastapi_streams.codegen.openapi import ContractError, Document, export_schema
 from fastapi_streams.codegen.writer import write_files
 
+if TYPE_CHECKING:
+    from fastapi_streams.codegen.diagnostics import GenerationDiagnostic
+
 
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="fastapi-streams")
@@ -30,6 +35,15 @@ def main(argv: list[str] | None = None) -> int:
             "--language", choices=["typescript", "python"], default="typescript"
         )
         command.add_argument("--output", required=True, type=Path)
+        command.add_argument("--diagnostics", type=Path, help="Write JSON diagnostics")
+        command.add_argument(
+            "--strict", action="store_true", help="Fail on unaccepted diagnostics"
+        )
+        command.add_argument(
+            "--allow-diagnostics",
+            type=Path,
+            help="JSON allowances with exact IDs and review reasons",
+        )
         command.add_argument(
             "--python-http-client",
             choices=["httpx", "httpx2"],
@@ -65,8 +79,23 @@ def main(argv: list[str] | None = None) -> int:
                 output.parent.mkdir(parents=True, exist_ok=True)
                 output.write_text(content, encoding="utf-8", newline="\n")
         else:
+            if args.diagnostics:
+                report = args.diagnostics.resolve()
+                output = args.output.resolve()
+                inputs = {args.schema.resolve()}
+                if args.allow_diagnostics:
+                    inputs.add(args.allow_diagnostics.resolve())
+                if report in inputs or report == output or output in report.parents:
+                    raise ContractError(
+                        "--diagnostics must be outside the generated output "
+                        "and input files"
+                    )
             if args.language != "python" and args.python_http_client is not None:
                 raise ContractError("--python-http-client requires --language python")
+            from fastapi_streams.codegen.diagnostics import (
+                accepted_diagnostics,
+                emit_diagnostics,
+            )
             from fastapi_streams.codegen.ir import build_ir
             from fastapi_streams.codegen.python import generate_python
             from fastapi_streams.codegen.typescript import generate_typescript
@@ -82,7 +111,29 @@ def main(argv: list[str] | None = None) -> int:
                         file=sys.stderr,
                     )
                     return 1
-            contract = build_ir(cast(Document, document))
+            diagnostics: list[GenerationDiagnostic] = []
+            contract = build_ir(
+                cast(Document, document), target=args.language, diagnostics=diagnostics
+            )
+            # Reports precede strict-policy failures, so CI can review new IDs.
+            if args.diagnostics:
+                _write_diagnostics(args.diagnostics, diagnostics, set())
+            accepted: set[str] = (
+                accepted_diagnostics(
+                    diagnostics, json.loads(args.allow_diagnostics.read_text("utf-8"))
+                )
+                if args.allow_diagnostics
+                else set()
+            )
+            if args.diagnostics:
+                _write_diagnostics(args.diagnostics, diagnostics, accepted)
+            pending = [item for item in diagnostics if item.id not in accepted]
+            emit_diagnostics(pending)
+            if args.strict and pending:
+                raise ContractError(
+                    f"{len(pending)} unaccepted generation diagnostics; "
+                    "review --diagnostics and provide explicit --allow-diagnostics"
+                )
             generated = (
                 generate_python(
                     contract, http_client=args.python_http_client or "httpx"
@@ -116,5 +167,27 @@ def _load_app(value: str) -> FastAPI:
     return app
 
 
+def _write_diagnostics(
+    path: Path, diagnostics: list[GenerationDiagnostic], accepted: set[str]
+) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(
+            {
+                "version": 1,
+                "diagnostics": [
+                    item.to_dict(accepted=item.id in accepted) for item in diagnostics
+                ],
+            },
+            indent=2,
+            sort_keys=True,
+            ensure_ascii=False,
+        )
+        + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+
+
 if __name__ == "__main__":
     sys.exit(main())