httpxgen 0.2.0__tar.gz → 0.4.0__tar.gz

{httpxgen-0.2.0 → httpxgen-0.4.0}/.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
           python-version: "3.14"
 
       - name: Install dependencies
-        run: uv sync --all-groups
+        run: uv sync --locked --all-groups
 
       - name: Ruff lint
         run: uv run ruff check --output-format=github .
@@ -36,7 +36,7 @@ jobs:
           python-version: "3.14"
 
       - name: Install dependencies
-        run: uv sync --all-groups
+        run: uv sync --locked --all-groups
 
       - name: Regenerate the preview client
         run: bash scripts/generate-preview.sh
@@ -58,7 +58,11 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync --all-groups
+        run: uv sync --locked --all-groups
 
       - name: Run tests
         run: uv run pytest
+
+      - name: Type-check generated protocols
+        if: matrix.python-version == '3.14'
+        run: uv run --frozen --with mypy==2.4.0 --with httpx2==2.13.1 pytest --no-cov tests/generator/test_typing.py

httpxgen-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,135 @@
+name: Release
+
+on:
+  pull_request:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.event.release.tag_name || github.head_ref || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build and verify distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.14"
+
+      - name: Validate release tag and source
+        if: github.event_name == 'release'
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          expected = f"v{version}"
+          if os.environ["RELEASE_TAG"] != expected:
+              raise SystemExit(f"Release tag must be {expected}")
+          PY
+          git merge-base --is-ancestor HEAD origin/main
+
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Lint and format
+        run: |
+          uv run ruff check --output-format=github .
+          uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Type-check generated protocols
+        run: uv run --frozen --with mypy==2.4.0 --with httpx2==2.13.1 pytest --no-cov tests/generator/test_typing.py
+
+      - name: Verify checked-in preview
+        run: |
+          bash scripts/generate-preview.sh
+          git diff --exit-code -- preview
+
+      - name: Build wheel and source distribution
+        run: uv build --no-sources
+
+      - name: Check distribution metadata
+        run: uvx --from twine twine check --strict dist/*
+
+      - name: Smoke-test the installed wheel outside the checkout
+        run: |
+          wheel="$(realpath dist/*.whl)"
+          cd "$RUNNER_TEMP"
+          uv run --isolated --no-project --with "$wheel" httpxgen --help
+          uv run --isolated --no-project --with "$wheel" httpxgen \
+            "$GITHUB_WORKSPACE/specs/api.yml" "$RUNNER_TEMP/release_smoke" \
+            --package-name release_smoke --tag payments --tag invoices
+          uv run --isolated --no-project --with "$wheel" httpxgen \
+            "$GITHUB_WORKSPACE/specs/api.yml" "$RUNNER_TEMP/release_smoke" \
+            --package-name release_smoke --tag payments --tag invoices --check
+
+      - name: Store verified distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/httpxgen/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download verified distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist
+
+      - name: Publish with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  release-assets:
+    name: Attach published distributions to GitHub Release
+    if: github.event_name == 'release'
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download published distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist
+
+      - name: Calculate checksums
+        working-directory: dist
+        run: sha256sum -- *.whl *.tar.gz > SHA256SUMS
+
+      - name: Upload release assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: gh release upload "$RELEASE_TAG" dist/* --repo "$GITHUB_REPOSITORY" --clobber

{httpxgen-0.2.0 → httpxgen-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: httpxgen
-Version: 0.2.0
+Version: 0.4.0
 Summary: Generate a typed async httpx client from an OpenAPI document.
 License-Expression: MIT
 License-File: LICENSE
@@ -38,6 +38,7 @@ the client, check it into your repository, review it, debug it, and ship it.
 - [Automation and CI](#automation-and-ci)
 - [Supported scope](#supported-scope)
 - [Development](#development)
+- [Releasing](#releasing)
 - [License](#license)
 
 ## Why httpxgen?
@@ -64,11 +65,10 @@ A regular specification becomes a self-contained Python package:
 openapi.json  ──▶  httpxgen  ──▶  payments/
                                     ├── __init__.py
                                     ├── client.py         # the public client class
-                                    ├── models.py
-                                    ├── exceptions.py     # generated client errors
-                                    ├── http_methods.py   # HttpMethods
+                                    ├── models.py         # API models, HttpMethods, HttpResponse
+                                    ├── errors.py         # generated client errors
                                     ├── serialization.py  # parameter and auth helpers
-                                    ├── transport.py      # structural protocols and file types
+                                    ├── transport.py      # HTTP client protocol and file types
                                     └── py.typed
 ```
 
@@ -79,9 +79,8 @@ models and support modules are generated once beside them:
 openapi.json  ──▶  httpxgen  ──▶  api/
                                     ├── __init__.py       # clients, ApiError, all models
                                     ├── shared/           # generated once
-                                    │     ├── exceptions.py
-                                    │     ├── http_methods.py
-                                    │     ├── models.py   # only models used by both tags
+                                    │     ├── errors.py
+                                    │     ├── models.py    # shared models, HttpMethods, HttpResponse
                                     │     ├── serialization.py
                                     │     └── transport.py
                                     ├── payments/
@@ -93,6 +92,10 @@ openapi.json  ──▶  httpxgen  ──▶  api/
                                     └── py.typed
 ```
 
+`HttpMethods` and `HttpResponse` live in `models.py` (`shared/models.py` in a
+workspace). Generated error classes live in `errors.py`. These types are also
+available from the package root.
+
 ## Install
 
 Requires Python 3.12 or newer.
@@ -200,7 +203,7 @@ imports stay short and stable.
 `operationId` becomes an idiomatic snake_case method, optional query parameters are only sent when set, and the response is validated into a model:
 
 `client.py` holds nothing but the imports and the client class — the serialization
-helpers live in `serialization.py`, the error type in `exceptions.py`:
+helpers live in `serialization.py`, the error type in `errors.py`:
 
 ```python
 class ListChargesParams(BaseModel):
@@ -291,7 +294,23 @@ Path parameters carry their spec format — `format: uuid` becomes `UUID`, not `
         raise ApiError(response.status_code, response.text, response=response)
 ```
 
-Request bodies are a single typed `body` argument, serialized by alias and without `None` noise:
+Request bodies are a single typed `body` argument, serialized by alias.
+JSON inputs are validated using the declared Pydantic schema before the HTTP
+transport runs, including mappings and model instances changed after creation.
+Invalid inputs raise `RequestValidationError`; Pydantic's normal accepted
+conversions apply before serialization.
+Unsupported runtime `content_type` choices also raise `RequestValidationError`
+before sending a request, with the declared alternatives listed.
+Explicitly supplied nullable fields are sent as JSON null; unset nullable fields
+are omitted, including inside nested models:
+
+For `application/merge-patch+json`, all unset model fields are omitted, including
+schema defaults. Explicit values equal to a default are still sent. Ordinary
+JSON create requests continue to include non-null defaults.
+
+Omit an optional JSON body by leaving out `body`. Passing `body=None` sends the
+literal JSON payload `null` when the schema permits null, with the selected JSON
+Content-Type. Omission uses a separate generated sentinel.
 
 ```python
     async def create_charge(
@@ -301,9 +320,7 @@ Request bodies are a single typed `body` argument, serialized by alias and witho
         timeout: float | None = None,
     ) -> Charge:
         ...
-        json_body = TypeAdapter(CreateChargeRequest).dump_python(
-            body, mode="json", by_alias=True, exclude_none=True
-        )
+        json_body = serialize_json_body(body, CreateChargeRequest)
         ...
 ```
 
@@ -311,10 +328,19 @@ The same direct shape is used for JSON, form, text, and small binary bodies.
 An `application/octet-stream` body accepts `bytes`, `Iterable[bytes]`, or
 `AsyncIterable[bytes]` and is passed directly as `content=`.
 
+Synchronous binary iterables are adapted lazily to async chunks. Exceptions
+raised while consuming an upload iterable are reported as `TransportError`.
+
 Multipart fields are flattened into method arguments. Binary arrays become
-repeated parts with the same wire name, while `UploadFile` carries optional
+repeated parts with the same wire name. Parameter and multipart argument names
+that collide with generated locals (such as `path`, `headers`, or `files`) gain
+an `_arg` suffix; their wire names are preserved. `UploadFile` carries optional
 per-part metadata without reading an open file eagerly:
 
+Bytes and default `UploadFile` inputs use the filename `upload`; bare handles
+use their basename when available. Set `UploadFile(filename=None, ...)`
+explicitly to send a filename-less part.
+
 ```python
 await client.upload_documents(
     documents=[
@@ -332,6 +358,16 @@ call sites to pass fields directly.
 Successful binary responses also get a streaming context-manager variant. The
 buffered method remains available for small responses:
 
+For endpoints with mixed success representations, buffered methods return the
+declared bytes/model/text/None union. Streaming variants yield `BinaryStream`
+for binary content and the parsed value for JSON, text, or empty successes.
+
+Binary successes with declared headers return a typed result whose `body` is
+bytes and whose fields contain validated headers. Their streaming variants
+yield a corresponding `...Result...Stream` model with `body: BinaryStream` and
+the same header fields, validated before iteration. Endpoints without declared
+headers retain the direct bytes/`BinaryStream` API.
+
 ```python
 content = await client.download_recording(recording_id)
 
@@ -343,6 +379,7 @@ print(recording.media_type, recording.content_length, recording.filename)
 ```
 
 The streaming context owns the individual response only. The generated wrapper
+closes entered responses even when validation or reading is cancelled, and
 treats its injected HTTP client as borrowed, so closing the wrapper does not
 close a shared application transport:
 
@@ -359,10 +396,14 @@ await http_client.aclose()
 ```
 
 All operation failures derive from `ClientError`. `TransportError` retains its
-original `cause`, `ResponseValidationError` retains both the response and cause,
+original `cause`, including failures during binary iteration.
+`ResponseValidationError` retains both the response and cause,
 and `ApiError` exposes a parsed `detail` plus convenient `code` and `message`
 properties. `body` and `parsed_body` remain compatibility aliases for
 `raw_body` and `detail`.
+When an error declares headers, `detail` retains its typed result wrapper and
+header fields; `code`/`message` read its typed payload. Arbitrary user payloads
+with a property named `body` are not unwrapped.
 
 ### Generated models
 
@@ -530,7 +571,58 @@ client-check:
 
 ## Supported scope
 
-httpxgen targets ordinary OpenAPI 3.0 and 3.1 client specifications, not every
+HTTP header names merge case-insensitively. Configured values override generated
+defaults; operation header parameters override configured values; applied
+security credentials take precedence over both. Each logical header is sent once.
+
+Recursive array and `anyOf` aliases use lazy Python 3.12+ type aliases, including
+mutual recursion. Recursive nondiscriminated `oneOf` and reference-only aliases are rejected with
+an actionable error; ordinary aliases and recursive object models stay readable.
+
+Exact `oneOf` membership uses JSON types without string/number/boolean coercion.
+Formatted date/UUID strings remain valid, and mathematically integral JSON
+numbers count as integers. Zero or multiple matching branches are rejected.
+
+Query names beginning with `_` or `model_` receive a public `field`/`field_`
+prefix in generated signatures and query models. Their wire names and
+validation constraints remain intact.
+
+Leading-underscore schema properties also receive a `field` prefix (for example,
+`_id` becomes `field_id`) and keep an explicit wire alias. They are validated
+ordinary model fields, including when additional properties are forbidden.
+
+Operation names that collide with generated lifecycle methods or streaming
+companions fail generation before writing files; rename the conflicting
+`operationId` in the specification.
+
+Local Path Item references are resolved before schema normalization and tag
+selection. Authored siblings replace the corresponding inherited fields;
+omitted siblings preserve inherited parameters and operations. Cycles fail
+generation with a specific error.
+
+References to nullable object components accept null in response bodies, request
+arguments, and nested fields while keeping the object model's required fields
+and constraints. OpenAPI 3.0 `nullable` requires an explicit type.
+
+URL-encoded forms honor supported per-field style/explode encodings and JSON
+contentType. Object values use JSON by default; explicit form styles can flatten
+simple objects. Unsupported encoding options (including form allowReserved)
+fail generation.
+
+Multipart object fields and object-array items are JSON parts with aliases and
+the declared `encoding.contentType` (JSON/+json), or application/json by default.
+File parts also honor `encoding.contentType`. Unsupported multipart encoding
+options fail generation explicitly.
+
+Dot-valued path identifiers (`.` and `..`) are percent-encoded to preserve the
+route boundary instead of allowing URL dot-segment normalization.
+
+Path `simple`, `label`, and `matrix` styles support scalar, flat array, and flat
+object values with their style-specific explode delimiters. Data is escaped
+before joining it, including literal commas, label dots, slashes, and percent
+signs. `allowReserved` applies only to query parameters.
+
+httpxgen targets ordinary OpenAPI 3.0, 3.1 and 3.2 client specifications, not every
 JSON Schema feature. It supports JSON/YAML input, local component references,
 path/query/header/cookie serialization, JSON/form/multipart/binary request
 bodies, JSON/text/binary responses, numeric/default/status-range responses,
@@ -539,12 +631,56 @@ security schemes, directional request/response models, inline and recursive
 Pydantic models, enums, nullable values, discriminated unions, and practical
 `allOf` inheritance.
 
+`allOf` supports object-model inheritance. Scalar/array intersections and
+nullable or union bases fail generation with an unsupported-composition error.
+
+Required object keys without declared property schemas retain presence checks
+and their additional-property validation, including inherited and directional
+models. Their values remain unconstrained when additional properties are allowed.
+
+OpenAPI 3.2 documents are accepted with the same feature set as 3.1, plus
+reusable `components.mediaTypes` references. Streaming media types described
+through `itemSchema` (for example Server-Sent Events or JSON Lines), `QUERY`
+operations, `additionalOperations`, and `querystring` parameters are not
+generated and fail with an explicit error. Mixed REST/streaming documents can
+still produce a REST client: select the REST operations with `--tag` and keep
+the event models with `--schema-tag`. Model selection follows `itemSchema` and
+`contentSchema`, so a payload such as
+`itemSchema.properties.data.contentSchema: {$ref: ...}` keeps its referenced
+models, including nested and recursive references:
+
+```sh
+httpxgen openapi.json src/api --tag rest --schema-tag sse
+```
+
 Unsupported constructs fail generation where possible. Important remaining
 limitations are external references, callbacks/webhooks, automatic
 pagination, and a synchronous client.
 
 ## Development
 
+String `format: byte` values use standard Base64 in JSON (OpenAPI 3.0 and the
+legacy format in 3.1). Python bytes hold decoded data; Base64 strings are decoded
+with strict alphabet/padding validation. Invalid response strings raise
+`ResponseValidationError`. This does not change `format: binary`, raw binary
+bodies, or multipart file uploads.
+
+Parameter `content` supports one JSON/+json representation for query, header,
+and path positions. Values are validated and serialized as one compact JSON
+value with aliases and formatted fields. Required nullable parameters send JSON
+null; optional `None` omits the parameter. JSON cookie content and combinations
+with schema/style/explode/allowReserved are rejected during generation.
+
+Query `allowReserved: true` preserves `:/?@!$'()*,;` and valid percent-encoded
+triples in values. It escapes `[]#&=+`, stray percent signs, and other disallowed
+characters to preserve query boundaries and form decoding. Parameter names,
+ordinary parameters, and query API keys retain normal escaping.
+
+Regeneration removes obsolete modules carrying the generator header inside the
+output package; `--check` reports them without changing files. Handwritten files
+and unmanaged `__init__.py`/`py.typed` files are preserved. Linked output paths
+are rejected instead of writing outside the package.
+
 ```sh
 uv sync --all-groups
 uv run pytest
@@ -552,6 +688,14 @@ uv run ruff check .          # lint
 uv run ruff format .         # format
 ```
 
+CI also checks generated transport/operation typing with Mypy against HTTPX and
+HTTPX2. Run that check locally with:
+
+```sh
+uv run --frozen --with mypy==2.4.0 --with httpx2==2.13.1 \
+  pytest --no-cov tests/generator/test_typing.py
+```
+
 `preview/` is generated output, checked in so the effect of a change is visible
 in review. Regenerate it whenever generated code changes — CI fails if it is
 stale:
@@ -560,6 +704,33 @@ stale:
 ./scripts/generate-preview.sh
 ```
 
+## Releasing
+
+Publishing a GitHub Release runs `.github/workflows/release.yml`, which builds
+and verifies the wheel and source distribution, publishes them to PyPI through
+Trusted Publishing, and attaches the same files plus `SHA256SUMS` to the release.
+Pull requests run the build and verification steps as a publishing dry run.
+
+1. Update `project.version` in `pyproject.toml`, run `uv lock` to synchronize
+   `uv.lock`, and finalize the version's changelog and migration notes.
+2. Merge the release preparation PR into `main` and wait for green CI.
+3. Create a GitHub Release with tag `v<project.version>` targeting that merged
+   commit. A draft does not publish anything; choose **Publish release** to
+   start the workflow.
+4. Wait for the **Release** workflow to finish and verify the new version on
+   [PyPI](https://pypi.org/project/httpxgen/).
+
+The workflow rejects tags that do not match `project.version` or point to a
+commit outside `main`. The PyPI Trusted Publisher must name repository
+`mathisarends/httpxgen`, workflow `release.yml`, and environment `pypi`.
+The publishing job uses that GitHub environment and `id-token: write`; no PyPI
+API token is required. Any configured environment approval must be completed
+before the publishing job can run.
+
+The tagged commit must contain the release workflow. For the first automated
+release, merge this workflow before creating the tag. If reusing an existing
+draft, update its target commit and release notes before publishing it.
+
 ## License
 
 MIT