httpxgen 0.1.0__tar.gz

httpxgen-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+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

httpxgen-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Testing / coverage
+.tmp/
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+.ruff_cache/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

httpxgen-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

httpxgen-0.1.0/CLAUDE.md

@@ -0,0 +1,6 @@
+# httpxgen
+
+## Conventions
+
+- In `__init__.py` files, use relative imports (e.g. `from .generator import ...`). Everywhere else, use absolute imports (`from httpxgen.generator import ...`).
+- No blanket module-level docstrings/comments at the top of files (e.g. `"""Renders a typed async httpx client..."""`).

httpxgen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mathisarends
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

httpxgen-0.1.0/PKG-INFO

@@ -0,0 +1,445 @@
+Metadata-Version: 2.5
+Name: httpxgen
+Version: 0.1.0
+Summary: Generate a typed async httpx client from an OpenAPI document.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# httpxgen
+
+Generate a **typed async [httpx](https://www.python-httpx.org/) client** from an OpenAPI document — no runtime layer, no reflection, no magic.
+
+httpxgen emits plain Python you could have written by hand: `async def` methods with real parameter names, [Pydantic](https://docs.pydantic.dev/) models for every schema, discriminated unions for `oneOf`, `StrEnum` for enums, and `UUID` / `datetime` where the spec says so. Check the output into your repo, read it, click through it in your editor.
+
+```
+openapi.json  ──▶  httpxgen  ──▶  payments/
+                                    ├── __init__.py
+                                    ├── client.py         # the public client class
+                                    ├── models.py
+                                    ├── exceptions.py     # ApiError
+                                    ├── http_methods.py   # HttpMethods
+                                    ├── serialization.py  # parameter and auth helpers
+                                    └── py.typed
+```
+
+Split a large document along its tags and the support modules are generated once,
+beside the clients that share 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
+                                    │     └── serialization.py
+                                    ├── payments/
+                                    │     ├── client.py
+                                    │     └── models.py   # models only payments uses
+                                    ├── invoices/
+                                    │     ├── client.py
+                                    │     └── models.py
+                                    └── py.typed
+```
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install httpxgen      # standalone CLI
+uv add --dev httpxgen         # dev dependency of your project
+```
+
+With pip:
+
+```sh
+pip install httpxgen
+```
+
+Or run it without installing anything:
+
+```sh
+uvx httpxgen openapi.json src/payments
+```
+
+httpxgen is only needed at build time — the generated package depends on `httpx` and `pydantic` alone.
+
+## Quick start
+
+```sh
+httpxgen openapi.yaml src/payments --package-name payments
+```
+
+```
+Generated 6 file(s) in package src/payments.
+```
+
+```python
+import asyncio
+
+import httpx
+
+from payments import ApiError, CardPaymentMethod, CreateChargeRequest, Money, PaymentsClient
+
+
+async def main() -> None:
+    async with PaymentsClient(
+        httpx.AsyncClient(),
+        "https://payments.example.com/api",
+        credentials={"bearerAuth": "your-token"},
+    ) as client:
+        page = await client.list_charges(status="succeeded", page_size=50)
+        for charge in page.items:
+            print(charge.id, charge.amount.amount_cents, charge.status)
+
+        try:
+            charge = await client.create_charge(
+                CreateChargeRequest(
+                    amount=Money(amount_cents=4200, currency="EUR"),
+                    payment_method=CardPaymentMethod(...),
+                )
+            )
+        except ApiError as error:
+            print(error.status_code, error.body)
+            if error.parsed_body is not None:
+                print(error.parsed_body)
+
+
+asyncio.run(main())
+```
+
+## What the generated code looks like
+
+### From this spec
+
+```yaml
+/charges:
+  get:
+    operationId: listCharges
+    parameters:
+      - name: status
+        in: query
+        schema: { $ref: "#/components/schemas/ChargeStatus" }
+      - name: cursor
+        in: query
+        schema: { type: string }
+      - name: page_size
+        in: query
+        schema: { type: integer, default: 25, minimum: 1, maximum: 200 }
+    responses:
+      "200":
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ChargePage" }
+```
+
+### You get this client
+
+`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`:
+
+```python
+class ListChargesParams(BaseModel):
+    status: ChargeStatus | None = None
+    cursor: str | None = None
+    page_size: int = Field(25, ge=1, le=200)
+
+
+class PaymentsClient:
+    async def list_charges(
+        self,
+        status: ChargeStatus | None = None,
+        cursor: str | None = None,
+        page_size: int = 25,
+        *,
+        timeout: float | None = None,
+    ) -> ChargePage:
+        path = "/charges"
+
+        params = ListChargesParams(
+            status=status,
+            cursor=cursor,
+            page_size=page_size,
+        )
+        query: list[tuple[str, str]] = []
+        if params.status is not None:
+            query.extend(serialize_query("status", params.status))
+        if params.cursor is not None:
+            query.extend(serialize_query("cursor", params.cursor))
+        query.extend(serialize_query("page_size", params.page_size))
+
+        headers = dict(self._headers)
+        headers.setdefault("Accept", "application/json")
+
+        apply_security(self._credentials, [("bearerAuth",)], headers, query, {})
+
+        response = await self._client.request(
+            method=HttpMethods.GET,
+            url=f"{self._base_url}{path}",
+            params=query,
+            headers=headers,
+            timeout=self._timeout if timeout is None else timeout,
+        )
+
+        if response.status_code == 200:
+            return ChargePage.model_validate(response.json())
+
+        raise ApiError(response.status_code, response.text, response=response)
+```
+
+Path parameters carry their spec format — `format: uuid` becomes `UUID`, not `str`:
+
+```python
+    async def get_customer(
+        self,
+        customer_id: UUID,
+        *,
+        timeout: float | None = None,
+    ) -> Customer:
+        path = "/customers/{customerId}"
+        path = path.replace("{customerId}", serialize_path("customerId", customer_id))
+
+        headers = dict(self._headers)
+        headers.setdefault("Accept", "application/json")
+
+        response = await self._client.request(
+            method=HttpMethods.GET,
+            url=f"{self._base_url}{path}",
+            headers=headers,
+            timeout=self._timeout if timeout is None else timeout,
+        )
+
+        if response.status_code == 200:
+            return Customer.model_validate(response.json())
+        if response.status_code == 404:
+            parsed_body = ApiErrorModel.model_validate(response.json())
+            raise ApiError(response.status_code, response.text, parsed_body, response)
+
+        raise ApiError(response.status_code, response.text, response=response)
+```
+
+Request bodies are a single typed `body` argument, serialized by alias and without `None` noise:
+
+```python
+    async def create_charge(
+        self,
+        body: CreateChargeRequest,
+        *,
+        timeout: float | None = None,
+    ) -> Charge:
+        ...
+        json_body = TypeAdapter(CreateChargeRequest).dump_python(
+            body, mode="json", by_alias=True, exclude_none=True
+        )
+        ...
+```
+
+The same direct shape is used for other ordinary body encodings:
+`application/x-www-form-urlencoded` is passed as `data=`, multipart object
+fields are separated into `data=` and `files=`, and binary payloads use
+`content=`. Multipart boundaries remain under `httpx`'s control.
+
+The client is an async context manager, so `httpx` connections are closed for you:
+
+```python
+http_client = httpx.AsyncClient()
+async with PaymentsClient(
+    http_client,
+    "https://payments.example.com/api",
+    credentials={"bearerAuth": "your-token"},
+) as client:
+    ...
+```
+
+### And these models
+
+`allOf` becomes inheritance, `oneOf` + `discriminator` becomes a Pydantic discriminated union, string enums become `StrEnum`, and `minimum` / `maxLength` survive as `Field(...)` constraints:
+
+```python
+class ChargeStatus(StrEnum):
+    PENDING = "pending"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    REFUNDED = "refunded"
+
+
+class Money(BaseModel):
+    amount_cents: int
+    currency: str = Field(min_length=3, max_length=3)
+
+
+class CardPaymentMethod(BaseModel):
+    type: Literal[PaymentMethodType.CARD]
+    card_number: str
+    exp_month: int = Field(ge=1, le=12)
+    exp_year: int
+    billing_address: Address | None = None
+
+
+PaymentMethod = Annotated[
+    CardPaymentMethod | BankTransferPaymentMethod,
+    Field(discriminator="type"),
+]
+
+
+class BaseEntity(BaseModel):
+    id: str
+    created_at: datetime
+
+
+class Charge(BaseEntity):          # allOf: BaseEntity + own properties
+    amount: Money
+    status: ChargeStatus
+    payment_method: PaymentMethod  # discriminated at parse time
+    metadata: dict[str, str] | None = None
+```
+
+Everything is re-exported from the package root, so consumers import from one place:
+
+```python
+from payments import ApiError, Charge, ChargeStatus, Money, PaymentsClient
+```
+
+## CLI
+
+```
+httpxgen OPENAPI OUTPUT [--package-name NAME] [--tag TAG] [--schema-tag TAG] [--check]
+```
+
+| Argument | Meaning |
+| --- | --- |
+| `OPENAPI` | OpenAPI JSON or YAML file |
+| `OUTPUT` | target package directory, or the root holding one package per tag when several `--tag` are given (created if missing) |
+| `--package-name` | import name and client class prefix; defaults to the output directory name |
+| `--tag TAG` | generate only operations carrying this tag; repeat it for one package per tag |
+| `--schema-tag TAG` | keep schemas referenced by this tag without generating its operations; repeatable |
+| `--check` | write nothing; exit non-zero when the checked-in output is stale |
+
+Carve a focused client out of a large spec:
+
+```sh
+httpxgen openapi.json src/billing \
+  --package-name billing \
+  --tag charges \
+  --schema-tag webhooks
+```
+
+Repeat `--tag` and you get one client package per tag. `ApiError`, `HttpMethods`,
+and the serialization helpers are generated once in `shared/`, and every model lands in
+the package that uses it — `shared/models.py` holds only what more than one tag
+references. Generated modules import each other absolutely, so the output reads
+the same wherever you open it:
+
+```sh
+httpxgen specs/api.yml src/api --package-name api --tag payments --tag invoices
+```
+
+```python
+# src/api/invoices/client.py
+from api.invoices.models import CreateInvoiceRequest, Invoice, InvoicePage
+from api.shared import ApiError, HttpMethods, apply_security, serialize_path
+from api.shared.models import ApiErrorModel
+```
+
+```python
+from api import ApiError, InvoicesClient, Money, PaymentsClient
+```
+
+Every managed file starts with a `# Generated by httpxgen. DO NOT EDIT.` header. Files without it are never overwritten — httpxgen aborts instead.
+
+## Use it from a shell script
+
+Generated code is checked in, so a tiny script is usually all the automation you need.
+
+`scripts/generate-client.sh`:
+
+```sh
+#!/usr/bin/env sh
+set -eu
+
+SPEC_URL="https://payments.example.com/api/openapi.json"
+OUT="src/payments"
+
+curl -fsSL "$SPEC_URL" -o openapi.json
+uvx httpxgen openapi.json "$OUT" --package-name payments
+
+echo "client regenerated in $OUT"
+```
+
+```sh
+chmod +x scripts/generate-client.sh
+./scripts/generate-client.sh
+```
+
+Use the `--check` variant in CI so a drifting spec fails the build instead of surprising you at runtime:
+
+```yaml
+# .github/workflows/client.yml
+- name: Verify generated client is current
+  run: |
+    curl -fsSL "$SPEC_URL" -o openapi.json
+    uvx httpxgen openapi.json src/payments --package-name payments --check
+```
+
+```
+Generated HTTP client is current.
+```
+
+Or wire it into a `Makefile`:
+
+```make
+.PHONY: client client-check
+
+client:
+	uvx httpxgen openapi.json src/payments --package-name payments
+
+client-check:
+	uvx httpxgen openapi.json src/payments --package-name payments --check
+```
+
+## Scope
+
+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
+bodies, JSON/text/binary responses, numeric/default/status-range responses,
+typed error bodies, common
+security schemes, directional request/response models, inline and recursive
+Pydantic models, enums, nullable values, discriminated unions, and practical
+`allOf` inheritance.
+
+Unsupported constructs fail generation where possible. Important remaining
+limitations are external references, streaming, callbacks/webhooks, automatic
+pagination, and a synchronous client.
+
+See [`MISSING_IMPL.md`](MISSING_IMPL.md) for the prioritized checklist and the
+test requirements for each future step.
+
+## Development
+
+```sh
+uv sync --all-groups
+uv run pytest
+uv run ruff check .          # lint
+uv run ruff format .         # format
+```
+
+`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:
+
+```sh
+./scripts/generate-preview.sh
+```
+
+## License
+
+MIT