httpxgen 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,64 +1,68 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-        with:
-          python-version: "3.14"
-
-      - name: Install dependencies
-        run: uv sync --all-groups
-
-      - name: Ruff lint
-        run: uv run ruff check --output-format=github .
-
-      - name: Ruff format
-        run: uv run ruff format --check .
-
-  preview:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-        with:
-          python-version: "3.14"
-
-      - name: Install dependencies
-        run: uv sync --all-groups
-
-      - name: Regenerate the preview client
-        run: bash scripts/generate-preview.sh
-
-      - name: Fail if the checked-in preview is stale
-        run: git diff --exit-code -- preview
-
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.12", "3.13", "3.14"]
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Install dependencies
-        run: uv sync --all-groups
-
-      - name: Run tests
-        run: uv run pytest
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Ruff lint
+        run: uv run ruff check --output-format=github .
+
+      - name: Ruff format
+        run: uv run ruff format --check .
+
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Regenerate the preview client
+        run: bash scripts/generate-preview.sh
+
+      - name: Fail if the checked-in preview is stale
+        run: git diff --exit-code -- preview
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        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.2.0 → httpxgen-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: httpxgen
-Version: 0.2.0
+Version: 0.3.0
 Summary: Generate a typed async httpx client from an OpenAPI document.
 License-Expression: MIT
 License-File: LICENSE
@@ -291,7 +291,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 +317,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 +325,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 +355,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 +376,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 +393,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,6 +568,57 @@ client-check:
 
 ## Supported scope
 
+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 and 3.1 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
@@ -539,12 +628,41 @@ 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.
+
 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 +670,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: