Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

unihttp-client

/unihttp-client

Generuje z OpenAPI 3.x typowany pakiet klienta API w Pythonie na bazie unihttp, z DTO, testami i konfiguracją.

Repozytorium
unihttp ↗
Licencja
MIT
Ostatnia zmiana repozytorium
30.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 30.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Generuje z OpenAPI 3.x typowany pakiet klienta API w Pythonie na bazie unihttp, z DTO, testami i konfiguracją.

Oryginalny opis (EN)

Generate a typed, packaged unihttp API client library (SDK) from an OpenAPI 3.x spec or a plain API description. Produces typed DTOs, BaseMethod definitions, a client class, ruff + mypy (strict) config, sensible contract tests, and packaging. Use when the user wants to scaffold, bootstrap, or generate an API client / SDK on top of unihttp.

Jak działa

  1. Workflow
  2. Output checklist
Sekcje z nagłówków SKILL.md, w oryginale · 193 linii, 1 340 słów
Podgląd SKILL.md
---
name: unihttp-client
description: Generate a typed, packaged unihttp API client library (SDK) from an OpenAPI 3.x spec or a plain API description. Produces typed DTOs, BaseMethod definitions, a client class, ruff + mypy (strict) config, sensible contract tests, and packaging. Use when the user wants to scaffold, bootstrap, or generate an API client / SDK on top of unihttp.
---

# unihttp client generator

Generate a **runnable, packaged API client** on top of `unihttp` from either an
OpenAPI 3.x specification or a written API description. The output is an
installable Python package with typed models, declarative methods, a client
class, `ruff` + `mypy` (strict) config, and a small set of common-sense tests.

Always write **idiomatic** unihttp code — load the companion `unihttp` skill (or
[../unihttp/SKILL.md](../unihttp/SKILL.md)) for the Wrong/Correct rules. The most
important one: **import from submodules** (`unihttp.method`, `unihttp.markers`,
`unihttp.bind_method`), never from the empty top-level `unihttp` package.

Defaults (override only when the user or spec asks):

- **unihttp version:** 0.4.0 or later for new packages. Respect existing version
  constraints and check feature availability when extending an older project.
- **Serializer:** adaptix + stdlib dataclasses.
- **Backend:** `aiohttp` async (`AiohttpAsyncClient`); use `requests`
  (`RequestsSyncClient`) when the user wants a synchronous client.
- **Layout:** one file per method, model, and enum (see
  [references/package-layout.md](references/package-layout.md)).
- **Tests:** contract tests at the unihttp seam (`build_http_request` /
  `make_response`) — only `pytest` needed, no HTTP-mock library.

Map OpenAPI constructs with [references/openapi-to-unihttp.md](references/openapi-to-unihttp.md).

## Workflow

### 1. Establish the input mode

- **OpenAPI spec** (file path, URL, or pasted document): confirm `openapi` is
  `3.0.x` or `3.1.x`. If it is older, ambiguous, or incomplete, say so before
  generating. Extract: tags / path groups, `operationId`s, parameters
  (path/query/header), request bodies, response schemas + status codes, reusable
  `components.schemas`, and security schemes. Flag hard constructs early:
  `oneOf`, `anyOf`, `allOf`, discriminators, multiple media types, file uploads.
- **API description** (no spec): gather, per endpoint, the method, URL template,
  path/query/header params, request body shape, and the response shape. Ask for
  the missing pieces rather than inventing them.

### 2. Confirm the essentials with the user (only what you cannot infer)

- Package/distribution name and import name.
- Sync or async (default async/aiohttp).
- Auth scheme (header token, bearer, API key, …) if the spec declares one.
- Whether to scaffold a fresh project or add the client into an existing repo.

Keep this short — infer sensible defaults and state them rather than
interrogating.

### 3. Plan the package layout

Mirror unihttp's own conventions: `src/<import_name>/` layout, `hatchling`
build, `ruff.toml` + `mypy.ini`, `py.typed`. Use **one file per symbol**:
`models/<model>.py`, `enums/<enum>.py`, `methods/<operation>.py`, and a single
`client.py`. Re-export the public surface from `__init__.py`. For a very small
API (a handful of endpoints), it is fine to collapse models into one
`models.py` — use judgement, do not over-fragment a 3-endpoint client.

The full tree and file templates are in
[references/package-layout.md](references/package-layout.md).

### 4. Generate DTOs (models and enums)

- One `@dataclass` per schema; one `enum.StrEnum`/`IntEnum` per enumerated type.
- Keep idiomatic snake_case Python fields. Preserve wire names via adaptix
  `name_mapping` in the client's `Retort`, not by renaming attributes.
- Split request and response models when the response adds server-owned fields
  (id, timestamps, computed values).
- Reuse shared schemas across operations instead of duplicating classes.
- Map `nullable` / `oneOf null` to `T | None`; `oneOf`/`anyOf` to `Union`;
  `allOf` to composition or a merged dataclass.

### 5. Generate methods

One method per operation, in `methods/<operation>.py`. Use
`BaseMethod[ResponseType]` for buffered results and `StreamMethod` when callers
need incremental response consumption:

- Class name from `operationId` (PascalCase); else `<Verb><Resource>`
  (`GetUser`, `CreateUser`, `ListUsers`).
- `__url__` = the path template, `__method__` = the HTTP verb (uppercase).
- Map parameters to markers (`Path`/`Query`/`Header`), request body to `Body`,
  form to `Form`, file uploads to `File` + `UploadFile`. See the mapping table.
- Use `Raw[bytes]` or `Raw[str]` for a prebuilt request body with Adaptix or a
  custom dumper; do not combine it with `Body`/`Form`/`File`.
- For `StreamMethod`, generate explicit status handling and show `.data` as a
  sync/async context manager. Follow the companion
  [streaming reference](../unihttp/references/streaming.md) for return types,
  cleanup, and retry limits.
- For paginated list endpoints, model the response envelope as a DTO (not a bare
  `list`) or expose page/offset as optional `Query` fields — see "Pagination" in
  the mapping reference. `datetime`/`date`/`UUID`/`Decimal`/`Enum` fields need no
  special handling (adaptix loads them from their standard string forms).
- The generic argument is the response model. Use `None` ONLY for a genuinely
  empty body (a real `204` with no content); if the endpoint returns an empty
  object `{}` (common for `DELETE`), use `BaseMethod[dict[str, Any]]` — `None`
  raises `TypeLoadError` because `make_response` always deserializes the body.

### 6. Generate the client

A single `*Client` subclass in `client.py`:

- Inherit `AiohttpAsyncClient` (async, default) or `RequestsSyncClient` (sync).
- Bind each operation with `bind_method`.
- Build a `Retort` (extend `DEFAULT_RETORT`) carrying any `name_mapping`, and
  pass `AdaptixDumper(retort)` / `AdaptixLoader(retort)`. The mapping must cover
  the **method** classes (`Body`/`Query` fields), not only response models — for
  an all-camelCase API use one global `name_mapping(map={...})` with no class
  predicate, which renames bodies, query filters, and models at once.
- Accept `base_url` and auth inputs in `__init__`; **default `base_url` from the
  spec's `servers[0].url`** so callers can construct the client with no args.
  Inject auth via a `Header` field on methods or an auth middleware
  (`AsyncMiddleware` for async clients; type `next_handler` as `AsyncHandler`).
- For endpoints needing pre/post logic, write an explicit method using
  `call_method` instead of `bind_method`.

### 7. Handle auth and errors

- Simple token/api-key auth: add it as a header (middleware or per-method
  `Header`). Leave a `TODO` for OAuth/refresh flows rather than inventing them.
- Map documented error status codes to exceptions with
  `AsyncErrorMapperMiddleware` / `SyncErrorMapperMiddleware`, or override
  `handle_error`. Keep a small exceptions module if the API has a real error
  taxonomy.
- Use the unihttp transport exceptions described in the companion skill. Opt
  into retries only when replaying the operation is safe; do not retry
  `NonRetryableError` or the base `UniHTTPError`.

### 8. Generate packaging

Produce `pyproject.toml` (hatchling, `src` layout), `ruff.toml`, `mypy.ini`,
`py.typed`, `.gitignore`, and a `README.md` with install + quickstart. Runtime
dependency is `unihttp` with the chosen extras, e.g.
`unihttp[aiohttp,adaptix]>=0.4.0`. Dev dependencies for the default tests are just
`ruff`, `mypy`, `pytest`. In `ruff.toml` use `extend-exclude` (not `exclude`) so
ruff keeps ignoring `.venv`. Templates in
[references/package-layout.md](references/package-layout.md).

### 9. Generate common-sense tests

Default to **contract tests** at the unihttp seam — they cover exactly what
generated code introduces and avoid flaky HTTP-mock dependencies:

- Per operation, assert `Method(...).build_http_request(dumper)` produces the
  right `url` / `method` / `query` / `body` (markers wired correctly).
- Per buffered response model, assert
  `Method(...).make_response(HTTPResponse(...), response_loader=loader)` parses
  into the right DTO. Call it by **keyword** (`response_loader=`) — that is how
  `call_method` invokes it, so a method overriding `make_response` with a wrong
  parameter name is caught instead of silently passing a positional test.
- For a generated streaming operation, check request construction, status
  rejection, and cleanup on early exit or a read error through a fake stream
  or local transport. `StreamMethod` has no `make_response` step.
- Request-building and buffered response-loading tests are synchronous and
  backend-agnostic — only `pytest` is needed, even for an async client. Async
  stream lifecycle tests additionally need an async test runner. See
  [references/package-layout.md](references/package-layout.md).

Optionally add **one** full-pipeline test through a mocked transport, but treat it
as an extra. Note that `aioresponses` lags new `aiohttp` releases (it breaks on
aiohttp 3.14), so pin a compatible pair, prefer `respx` for httpx clients, or use
a local `pytest-aiohttp` server. Skip property-based / contract fuzzing unless the
user asks.

### 10. Verify before claiming done

Run, from the generated package, and report real output:

```bash
ruff check .
ruff format --check .
mypy
pytest
```

Freshly generated code routinely needs one `ruff check --fix` + `ruff format`
pass before it is clean (import grouping, long `__all__` lines). Run those first,
then the gate. Fix what remains. Do not claim the package is correct until these
pass (or explicitly report what does not and why).

## Output checklist

- `pyproject.toml` (+ `ruff.toml`, `mypy.ini`, `py.typed`) when scaffolding a package.
- A DTO per request/response schema that matters; an enum per enumerated type.
- A `BaseMethod` or `StreamMethod` per operation; a single client binding them.
- A `Retort` carrying wire-name mappings when the API is not snake_case.
- Minimal contract tests (seam-level), or a clear note on why tests were skipped.
- `README.md` with install and a runnable quickstart (using `async with` for
  async clients).
- A short report of `ruff` / `mypy` / `pytest` results.
Pliki w paczce (4)
  • SKILL.md 10 KB
  • agents/openai.yml 1 KB
  • references/openapi-to-unihttp.md 12 KB
  • references/package-layout.md 12 KB

Wersje

W bazie nie ma innych skilli o nazwie unihttp-client.

Migawka bazy z 13.11.2026 · wersja paczki a93f575e159a (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95unihttp
    Pisze klientów HTTP w unihttp: definicje metod API, wybór serializera, obsługę błędów i middleware.
  • 100api-integrate
    Generuje typowane klienty API i DTO z OpenAPI lub Swagger przy integracji API.
  • 100api-sdk-generator
    Generuje kod SDK klienta, biblioteki wrapperów API, modele żądań i odpowiedzi oraz wzorce użycia w wybranym języku dla dowolnego API REST.
  • 100generating-api-sdks
    Generuje klienckie SDK w wielu językach ze specyfikacji OpenAPI, do konsumowania API.
  • 100generating-api-sdks
    Generuje klienckie SDK w wielu językach ze specyfikacji OpenAPI, do konsumowania API.
  • 100openapi-spec
    Pisze specyfikację OpenAPI 3.1, sprawdza ją Redocly CLI, generuje typy TypeScript i typowanego klienta fetch, buduje dokumentację HTML i pilnuje poprawności specyfikacji.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.