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

{fastapi_streams-0.0.1 → fastapi_streams-0.2.0}/.github/workflows/ci.yml

@@ -2,7 +2,9 @@ name: CI
 
 on:
   push:
+    branches: ["**"]
   pull_request:
+  workflow_call:
 
 permissions:
   contents: read
@@ -16,15 +18,17 @@ jobs:
       matrix:
         python: ["3.12", "3.13", "3.14"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: ${{ matrix.python }}
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: "24"
           cache: npm
-      - uses: astral-sh/setup-uv@v6
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.9.2"
           enable-cache: true
@@ -38,7 +42,7 @@ jobs:
       - run: npm run typecheck
       - run: npm run test:coverage
       - run: uv run pytest -q --cov --cov-report=term-missing --cov-report=xml:coverage-python.xml
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         if: always()
         with:
           name: coverage-python-${{ matrix.python }}
@@ -47,4 +51,5 @@ jobs:
             coverage-typescript.lcov
       - run: uv run python scripts/codegen.py --check
       - run: uv build
+      - run: uv run --frozen twine check --strict dist/*
       - run: uv run python scripts/check_package.py

{fastapi_streams-0.0.1 → fastapi_streams-0.2.0}/.github/workflows/compatibility.yml

@@ -2,7 +2,9 @@ name: Dependency compatibility
 
 on:
   push:
+    branches: ['**']
   pull_request:
+  workflow_call:
   workflow_dispatch:
   schedule:
     - cron: '17 7 * * 1'
@@ -22,22 +24,24 @@ jobs:
         python: ['3.12', '3.13', '3.14']
         dependencies: [lowest, latest]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: ${{ matrix.python }}
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: '24'
           cache: npm
-      - uses: astral-sh/setup-uv@v6
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: '0.9.2'
           enable-cache: true
       - run: npm ci --ignore-scripts
       - name: Resolve dependencies and run native FastAPI and client integration tests
         run: python scripts/test_compat.py --python ${{ matrix.python }} --dependencies ${{ matrix.dependencies }}
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         if: always()
         with:
           name: compatibility-${{ matrix.os }}-${{ matrix.python }}-${{ matrix.dependencies }}

fastapi_streams-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,115 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      prerelease: ${{ steps.version.outputs.prerelease }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - name: Validate tag, versions and main ancestry
+        id: version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: python scripts/check_release.py "$RELEASE_TAG" >> "$GITHUB_OUTPUT"
+
+  ci:
+    needs: validate
+    uses: ./.github/workflows/ci.yml
+
+  compatibility:
+    needs: validate
+    uses: ./.github/workflows/compatibility.yml
+
+  build:
+    needs: [validate, ci, compatibility]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '24'
+          cache: npm
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          version: '0.9.2'
+      - run: uv sync --locked --all-extras
+      - run: npm ci --ignore-scripts
+      # Build the wheel from the sdist, including packaged templates and schemas.
+      - run: uv build --no-sources
+      - run: uv run --frozen twine check --strict dist/*
+      - run: uv run --frozen python scripts/check_package.py
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: release-distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 30
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fastapi-streams
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: release-distributions
+          path: dist/
+      - name: Publish to PyPI with Trusted Publishing and attestations
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          attestations: true
+
+  github-release:
+    needs: [validate, publish]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: release-distributions
+          path: dist/
+      - name: Create GitHub Release with the published distributions
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ github.ref_name }}
+          PRERELEASE: ${{ needs.validate.outputs.prerelease }}
+        run: |
+          gh release create "$RELEASE_TAG" dist/* \
+            --verify-tag --generate-notes --title "$RELEASE_TAG" \
+            --prerelease="$PRERELEASE"

fastapi_streams-0.2.0/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+All notable changes and consumer upgrade steps are recorded here. Entries marked
+unreleased describe prepared source versions that have not been published.
+
+## 0.2.0 - 2026-10-18
+
+- Source preparation passed workspace CI, independent wheel matrices and the
+  package release dry run. See the [release preparation evidence](../../docs/releases.md#verified-follow-up-preparation-2026-10-18).
+
+### Added
+
+- Preserve supported string patterns/lengths and numeric bounds/multiples in the
+  codegen IR and generated Python Pydantic annotations, including nested and
+  referenced scalars. Diagnose unsupported constraints and regex expressions.
+- Add `RequestOptions(unknown_events="ignore")` to generated Python SDKs. It
+  skips unknown string tags in a top-level discriminated event union; the default
+  remains an error. Malformed known events, missing tags and invalid JSON fail.
+  Both HTTPX backends retain their validation and transport behavior.
+- Add tested contract-first native proxy and private OpenAPI 3.1 REST-codegen
+  recipes. The authoritative OpenAPI 3.2 artifact remains unchanged.
+
+### Breaking generated-code changes
+
+- Regenerated Python models enforce scalar rules that 0.1.0 silently dropped.
+  Fix invalid payloads before adopting the new SDK. Unsupported constraints emit
+  `UnsupportedConstraintWarning`; constraints alongside enum/const/composition
+  and unsupported Python regex patterns fail explicitly. Move supported scalar
+  constraints onto scalar branches where possible. This is not full JSON Schema
+  validation. TypeScript remains static-only.
+- Regenerate committed SDKs and run consumer validation tests. Pass HTTPX2
+  generation/check options consistently if used. No wire names change.
+
+### Upgrade from 0.1.0
+
+1. Update `fastapi-streams[codegen]` to 0.2.0 and regenerate both SDKs from the
+   authoritative OpenAPI document. Keep the selected Python HTTP backend on
+   generation and check commands.
+2. Fix data violating preserved scalar constraints and review all unsupported-rule
+   diagnostics. Re-run consuming client validation and stream tests.
+3. Keep the default unknown-event error policy, or opt in per request only where
+   the upstream intentionally emits additional top-level discriminator values.
+
+### Release verification
+
+- Extend installed-wheel HTTPX/HTTPX2 smoke consumers to verify scalar constraints,
+  default unknown-event rejection, opt-in skipping and malformed known events.
+
+### Documentation
+
+- Fix PyPI installation instructions and supported-scope wording. Replace the
+  predecessor release guide with the workspace release process.
+
+## 0.1.0 - 2026-10-17
+
+### Added
+
+- Generated TypeScript JSDoc and Python method docstrings include OpenAPI
+  summaries, descriptions, deprecation, and SDK-specific iteration, cancellation,
+  validation, and error behavior. Endpoint descriptions remain the source for
+  business guarantees such as retention or job lifetime after disconnect.
+- `OptionalDiscriminatorWarning` identifies optional discriminator fields in
+  stream event unions, including nested and referenced events. Diagnostics name
+  the operation, route, model, and field; generation preserves schema requiredness.
+- Explicit `OperationErrorBody` aliases in both SDKs distinguish declared HTTP
+  response bodies from thrown exceptions. Existing `OperationError` aliases remain
+  available; TypeScript marks them deprecated. Method documentation lists the
+  declared HTTP statuses and media types. Existing Python anonymous error-model
+  imports such as `OperationError0` retain their names.
+- TypeScript `isHttpError(error, isDetails)` narrows `HttpError.details` only after
+  a caller-supplied type guard succeeds. It adds no runtime dependencies or assumed
+  problem format. HTTP status and operation provenance remain caller checks.
+- Checked TypeScript and Python error-handling consumer examples, plus a
+  standalone FastAPI dependency/problem-response regression without an error
+  framework. Public generated error-alias name collisions now fail explicitly.
+
+### Changed
+
+- Develop in `mathisarends/canon`; package source, documentation, and issue URLs
+  now point to the monorepo.
+- Single-value string fields now use TypeScript/Python literals instead of
+  synthesizing a separate public constant object or `StrEnum` for every field.
+  Explicitly named enums, multi-value field enums, and shared event discriminator
+  enums remain available. TypeScript also omits unnecessary property quotes and
+  union parentheses while preserving intersection grouping and extra-field types.
+
+### Breaking generated-code changes
+
+- Synthesized single-field constants such as `InvalidCredentialsProblemTitle`
+  and `InvalidCredentialsProblemType` are no longer exported. Replace usages like
+  `InvalidCredentialsProblemTitle.INVALID_CREDENTIALS` with the wire literal
+  `"Invalid credentials"`, then remove unused imports. Python singleton fields
+  now contain plain strings instead of generated `StrEnum` members; replace
+  identity checks with value comparisons. Shared discriminator values such as
+  `RunEventType.RUN_STARTED` and explicit schema enums are unchanged.
+- Generated `OperationError`/`OperationErrorBody` names are reserved in both
+  SDKs. Python now reports collisions explicitly too. If a schema uses one of
+  these names, rename the colliding model or choose a distinct `operation_id`.
+
+### Upgrade from 0.0.1
+
+1. Update `fastapi-streams[codegen]` to `0.1.0`, using the same version for schema
+   export and both SDKs.
+2. Regenerate committed clients from the application's OpenAPI document. Existing
+   method names and call signatures are unchanged:
+
+   ```sh
+   uv run fastapi-streams schema --app your_app:app --output openapi.json
+   uv run fastapi-streams generate --schema openapi.json --language typescript --output generated/typescript
+   uv run fastapi-streams generate --schema openapi.json --language python --output generated/python
+   uv run fastapi-streams check --app your_app:app --schema openapi.json --language typescript --output generated/typescript
+   uv run fastapi-streams check --app your_app:app --schema openapi.json --language python --output generated/python
+   ```
+
+   Substitute the application's existing module and output paths. Preserve
+   `--python-http-client httpx2` on generation and checks if it is already used.
+3. Review optional discriminator warnings. For output-only Pydantic event models
+   whose defaults are always serialized, see the serialization configuration in
+   [the codegen guide](docs/codegen.md#event-discriminators). Do not make optional
+   request fields required merely because they have Python defaults. Add
+   endpoint-specific guarantees to OpenAPI descriptions. Export and regenerate
+   again after changing models or descriptions.
+4. Apply the single-field constant migration above if the application imported
+   these generated names. HTTP payloads, method names, and signatures are unchanged.
+5. Prefer `OperationErrorBody` over `OperationError` when referring to response
+   bodies. Keep caught errors unknown until checked; validate `HttpError.details`
+   with a body guard in TypeScript or Pydantic `TypeAdapter` in Python. See
+   [HTTP error contracts](docs/clients.md#http-error-contracts). Unexpected proxy
+   responses must continue through the generic `HttpError` fallback.
+6. Run the consuming project's TypeScript/Python type checks and stream tests.
+   Commit the exported schema and regenerated SDKs together with call-site updates.
+
+## 0.0.1
+
+- Initial typed GET/POST JSON SSE routers, OpenAPI export, TypeScript and Python
+  generators, shared transports, and contract/client drift checks.

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: fastapi-streams
-Version: 0.0.1
+Version: 0.2.0
 Summary: Typed FastAPI streams with generated TypeScript and Python clients.
-Project-URL: Documentation, https://github.com/mathisarends/fastapi-streams/tree/main/docs
-Project-URL: Source, https://github.com/mathisarends/fastapi-streams
-Project-URL: Issues, https://github.com/mathisarends/fastapi-streams/issues
+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
+Project-URL: Issues, https://github.com/mathisarends/canon/issues
 Author: Mathis Arends
 License-Expression: MIT
 License-File: LICENSE
@@ -45,10 +45,10 @@ A CI check catches drift between the Python app, the contract, and generated cod
 
 ## 1. Decorate your FastAPI endpoint
 
-Install from GitHub with the optional codegen extra:
+Install from PyPI with the optional codegen extra:
 
 ```sh
-uv add 'fastapi-streams[codegen] @ git+https://github.com/mathisarends/fastapi-streams.git'
+uv add 'fastapi-streams[codegen]'
 ```
 
 Save this as `app.py`:
@@ -224,6 +224,9 @@ and committed OpenAPI regression fixtures in `tests/fixtures/`. Verify all gener
 
 ## Documentation
 
+See the [changelog and upgrade steps](CHANGELOG.md) when updating the library
+and regenerating committed clients.
+
 | Guide | Topics |
 | --- | --- |
 | [Quickstart](docs/quickstart.md) | Setup, event models, and FastAPI integration. |
@@ -231,8 +234,10 @@ and committed OpenAPI regression fixtures in `tests/fixtures/`. Verify all gener
 | [Client usage](docs/clients.md) | Enums, authentication, cancellation, and errors. |
 | [Architecture](docs/architecture.md) | Native SSE, shared IR, templates, and transports. |
 | [Development](docs/development.md) | Tests, supported scope, and roadmap. |
+| [Releasing](docs/releasing.md) | Tag-based releases and credential-free PyPI publishing. |
 
-v0.0.1 supports GET/POST JSON SSE streams. Ordinary REST endpoints stay in the
-contract for your existing REST SDK. See the [supported scope](docs/development.md#supported-scope-and-roadmap).
+The current release supports GET/POST JSON SSE streams. Ordinary REST endpoints
+stay in the contract for your existing REST SDK. See the
+[supported scope](docs/development.md#supported-scope-and-roadmap).
 
 Python 3.12+ · FastAPI 0.143.3+ · Pydantic v2 · [MIT](LICENSE)

{fastapi_streams-0.0.1 → fastapi_streams-0.2.0}/README.md

@@ -27,10 +27,10 @@ A CI check catches drift between the Python app, the contract, and generated cod
 
 ## 1. Decorate your FastAPI endpoint
 
-Install from GitHub with the optional codegen extra:
+Install from PyPI with the optional codegen extra:
 
 ```sh
-uv add 'fastapi-streams[codegen] @ git+https://github.com/mathisarends/fastapi-streams.git'
+uv add 'fastapi-streams[codegen]'
 ```
 
 Save this as `app.py`:
@@ -206,6 +206,9 @@ and committed OpenAPI regression fixtures in `tests/fixtures/`. Verify all gener
 
 ## Documentation
 
+See the [changelog and upgrade steps](CHANGELOG.md) when updating the library
+and regenerating committed clients.
+
 | Guide | Topics |
 | --- | --- |
 | [Quickstart](docs/quickstart.md) | Setup, event models, and FastAPI integration. |
@@ -213,8 +216,10 @@ and committed OpenAPI regression fixtures in `tests/fixtures/`. Verify all gener
 | [Client usage](docs/clients.md) | Enums, authentication, cancellation, and errors. |
 | [Architecture](docs/architecture.md) | Native SSE, shared IR, templates, and transports. |
 | [Development](docs/development.md) | Tests, supported scope, and roadmap. |
+| [Releasing](docs/releasing.md) | Tag-based releases and credential-free PyPI publishing. |
 
-v0.0.1 supports GET/POST JSON SSE streams. Ordinary REST endpoints stay in the
-contract for your existing REST SDK. See the [supported scope](docs/development.md#supported-scope-and-roadmap).
+The current release supports GET/POST JSON SSE streams. Ordinary REST endpoints
+stay in the contract for your existing REST SDK. See the
+[supported scope](docs/development.md#supported-scope-and-roadmap).
 
 Python 3.12+ · FastAPI 0.143.3+ · Pydantic v2 · [MIT](LICENSE)

{fastapi_streams-0.0.1 → fastapi_streams-0.2.0}/docs/README.md

@@ -7,8 +7,10 @@ TypeScript Fetch and Python HTTPX clients from the same definitions.
 | --- | --- |
 | [Quickstart](quickstart.md) | Run the complete example and define your first stream. |
 | [Contracts and codegen](codegen.md) | Export OpenAPI, generate both clients, and detect drift in CI. |
+| [Native transports](native-transports.md) | Existing SSE proxies, contract-first generation and private REST codegen views. |
 | [Client usage](clients.md) | Named event values, typed iteration, authentication, cancellation, and errors. |
 | [Development](development.md) | Local checks, test coverage, supported features, and roadmap. |
+| [Releasing](releasing.md) | Workspace release preparation, PyPI publishing, and recovery. |
 | [Architecture](architecture.md) | Server integration, shared IR, generation, and transport boundaries. |
 
 Start with the [quickstart](quickstart.md), then use the

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

@@ -5,8 +5,10 @@
 ## Named values and typed iteration
 
 Discriminated unions produce an enum named after the union and discriminator:
-`RunEvent` + `type` becomes `RunEventType`. String enums and literal model fields
-also get named values. Python emits `StrEnum`; TypeScript emits an `as const`
+`RunEvent` + `type` becomes `RunEventType`. Named string enums and multi-value
+literal model fields also get named values. Single constant fields, such as
+problem titles and URIs, remain inline literals. Python emits `StrEnum` for enums;
+TypeScript emits an `as const`
 object plus a union type. Both retain exhaustive discriminator narrowing.
 Parameters use camelCase in TypeScript and snake_case in Python; wire aliases
 are preserved.
@@ -117,6 +119,54 @@ Pydantic; TypeScript provides static types and JSON decoding, with no runtime
 schema validator. Cancellation propagates normally; application error events
 remain ordinary members of the user-defined union.
 
+## HTTP error contracts
+
+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
+HTTP failures with FastAPI's `responses=`; put authentication, authorization,
+and resource checks in dependencies so they can fail before the response starts.
+Even generator statements before the first `yield` execute after response start.
+
+Each operation with declared error schemas exports an `OperationErrorBody`
+union: for example `StreamRunEventsErrorBody`. The earlier `OperationError`
+name remains an alias for compatibility; it describes response bodies, not
+the exceptions thrown by the SDK. Python imports these aliases from `models`;
+TypeScript exports them from the SDK entrypoint.
+
+Catch HTTP failures around **iteration**, since opening the request is lazy.
+`HttpError.details` deliberately remains unvalidated: proxies and servers can
+return unexpected JSON, plain text, HTML, incomplete bodies, or no body at all.
+An operation's body union does not associate each variant with a status and does
+not prove which operation produced an exception. Check the actual HTTP status
+and validate the body before using application fields.
+
+TypeScript provides `isHttpError(error, isDetails)`. Supply a type guard that
+checks every field promised by its return type, or adapt an existing runtime
+validator. The helper verifies the SDK exception class and invokes that guard;
+it does not generate a schema validator or validate the HTTP status. A generic
+type argument alone cannot replace the required guard. Failed guards leave the
+original `HttpError` available for generic handling.
+
+Python can validate `error.details` with `TypeAdapter(OperationErrorBody)` and
+handle `ValidationError` as an unexpected response. Both approaches retain
+the original status, response, and diagnostics. Schema unions with permissive
+variants may accept a broad range of bodies; inspect the parsed variant before
+using its fields. Existing limits on bounded HTTP diagnostics still apply.
+
+The checked consumer examples show HTTP validation errors, fallback handling,
+stream parsing/transport errors, and ordinary application error events:
+
+- [TypeScript error handling](../examples/agent_runs/errors.ts), compiled with the
+  generated SDK under the repository's strict TypeScript configuration.
+- [Python error handling](../examples/agent_runs/errors.py), checked by Pyright
+  with the generated models.
+
+Caller cancellation continues to propagate. Neither SDK converts application
+error events into exceptions or automatically retries a stream.
+
+## Python model fields
+
 Python uses `None` for omitted optional fields; `model_fields_set` distinguishes
 absence from explicit null. Explicit null is rejected for fields that may only
 be omitted. Requests exclude unset fields and serialize using wire aliases.

fastapi_streams-0.2.0/docs/codegen.md

@@ -0,0 +1,156 @@
+# Contracts and client generation
+
+[Documentation](README.md) · [Project](../README.md)
+
+## Export and generate
+
+```sh
+uv run fastapi-streams schema \
+  --app examples.agent_runs:app --output tests/fixtures/agent_runs.openapi.json
+
+uv run fastapi-streams generate \
+  --schema tests/fixtures/agent_runs.openapi.json --language typescript --output frontend/generated
+
+uv run fastapi-streams generate \
+  --schema tests/fixtures/agent_runs.openapi.json --language python --output myapp/generated
+```
+
+No running server is needed. Export imports the application. The codegen extra
+adds Jinja and JSON Schema validation; importing the server package needs neither.
+
+The exporter copies native FastAPI output, promotes compatible 3.1 output to
+OpenAPI 3.2.0, updates the declared OAS dialect when necessary, and validates the
+official bundled OpenAPI structural schema, Draft 2020-12 Schema Objects and
+local references. Incompatible contracts fail explicitly. The application's
+cached document and ordinary REST endpoints remain intact.
+
+The generator extracts application data from
+`itemSchema.properties.data.contentSchema`. Only stream operations and models
+reachable from their parameters, bodies, events and error responses are emitted.
+Operations use the first tag as their group, defaulting to `streams`.
+
+Generated method documentation carries each operation's `summary`, `description`,
+and `deprecated` marker alongside language-specific SDK behavior. Describe
+replay, retention, and server job lifetime explicitly on your endpoint; the
+generator does not infer these business guarantees. Python early exits should
+use `contextlib.aclosing`; TypeScript `for await` cleanup closes its reader.
+
+TypeScript has no runtime dependencies and uses Fetch-compatible APIs. The
+example uses ES modules and is tested on Node 24. Generated Python packages
+require Python 3.12+, `httpx>=0.28` and `pydantic>=2.11.2` (`uv add httpx pydantic`).
+
+HTTPX is the default. To generate a Python client using HTTPX2 instead, opt in
+when generating and checking it:
+
+```sh
+uv run fastapi-streams generate \
+  --schema tests/fixtures/agent_runs.openapi.json --language python \
+  --python-http-client httpx2 --output myapp/generated
+
+uv run fastapi-streams check \
+  --schema tests/fixtures/agent_runs.openapi.json --language python \
+  --python-http-client httpx2 --output myapp/generated
+```
+
+Install `httpx2>=2.13.1,<3` and `pydantic>=2.11.2` in that consumer. The
+generated package needs only the selected HTTP library; installing HTTPX2 does
+not change an existing HTTPX client. The Python generator API accepts the same
+choice as `generate_python(contract, http_client="httpx2")`. Pass the choice to
+every `check` or `generate --check` call; omitting it checks HTTPX output.
+`--python-http-client` requires `--language python`.
+
+REST operations remain available in the contract for an existing SDK generator
+such as Orval or HeyAPI. Keep REST and streaming SDKs in separate output
+directories. Reusing external generated model imports is a future feature.
+
+## Event discriminators
+
+A Python default allows omitting a field when constructing a model. It does not
+automatically make the field required in JSON Schema. The generator respects
+`required` and warns with `OptionalDiscriminatorWarning` when a stream event
+union uses an optional discriminator, including nested unions. An absent tag may
+prevent variant selection; TypeScript's static types do not validate incoming JSON.
+
+For **output-only** event models whose serializer always emits default fields,
+configure the output schema to describe that behavior:
+
+```python
+from pydantic import BaseModel, ConfigDict
+
+
+class StreamEvent(BaseModel):
+    model_config = ConfigDict(
+        json_schema_mode_override="serialization",
+        json_schema_serialization_defaults_required=True,
+    )
+```
+
+Inherit event variants from this model, or apply the configuration to an existing
+output-only base. It marks all serialized default fields required, not only the
+discriminator. Avoid applying it globally to shared request models: input and
+output requiredness can differ. Alternatively, declare the tag without a default
+and pass it explicitly. Regenerate the schema and clients after changing models.
+
+Warnings are advisory and do not change fields or defaults. Python callers can
+filter or promote this category using the standard `warnings` module; the category
+is available from `fastapi_streams.codegen.diagnostics`.
+
+## Check drift in CI
+
+```sh
+uv run fastapi-streams check \
+  --app examples.agent_runs:app --schema tests/fixtures/agent_runs.openapi.json \
+  --language typescript --output examples/agent_runs/generated
+
+uv run fastapi-streams check \
+  --app examples.agent_runs:app --schema tests/fixtures/agent_runs.openapi.json \
+  --language python --output examples/agent_runs/generated_python
+```
+
+`check` imports the app, compares its contract, validates the stored schema and
+compares generated files without writing. Omit `--app` for a contract supplied
+by another service. `schema --check` and `generate --check` are also supported.
+Exit codes: **0** current, **1** drift, **2** invalid input.
+
+Generation is deterministic. A manifest tracks owned files and cleans up stale
+generated files without deleting neighboring handwritten files. Use a dedicated
+output directory for each language. Unsafe paths and generated-name collisions
+fail explicitly.
+
+## Runtime validation and unknown variants
+
+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
+models, arrays, nullable types and referenced scalar aliases. Patterns use
+Pydantic's Rust regex engine; unsupported expressions fail generation. Numeric
+multiples follow Pydantic's floating-point tolerance. This is not a complete JSON
+Schema validator. Formats, collection/object limits and other unsupported rules
+emit `UnsupportedConstraintWarning`; promote it to an error in CI when required.
+Constraints alongside enum/const or composition fail explicitly; constraints on
+scalar branches are supported. TypeScript provides static shapes and does not
+validate incoming JSON or enforce scalar constraints at runtime.
+
+Python event unions are closed by default: unknown variants raise
+`StreamParseError`. For an upstream that emits more variants than your declared
+subset, explicitly choose a per-request policy:
+
+```python
+from generated import RequestOptions
+
+options = RequestOptions(unknown_events="ignore")
+async for event in client.runs.run_events(run_id="run_abc", options=options):
+    ...
+```
+
+Ignoring requires a top-level discriminated union with known string tags. Only
+valid JSON objects with an unknown string discriminator are skipped. Invalid
+JSON, missing/non-string discriminators and malformed known variants still fail;
+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.
+
+## Existing native streams and mixed REST generation
+
+See the [native transport and mixed-codegen recipe](native-transports.md) when
+an existing generator, native server or byte-preserving proxy owns the stream.

{fastapi_streams-0.0.1 → fastapi_streams-0.2.0}/docs/development.md

@@ -17,6 +17,7 @@ npm run test:coverage
 uv run pytest -q --cov --cov-report=term-missing --cov-report=xml:coverage-python.xml
 uv run python scripts/codegen.py --check
 uv build
+uv run --frozen twine check --strict dist/*
 uv run python scripts/check_package.py
 ```