# The Python package

A package for Python 3.11 or newer, with one dependency, `httpx`. It has a sync and an async client, and type hints throughout.

## Its files

| File | What it holds |
| --- | --- |
| `pyproject.toml` | The name, version, `requires-python = ">=3.11"`, the `httpx` dependency, and pyright in strict mode. |
| `src/<module>/_client.py` | The sync and async clients. |
| `src/<module>/resources/` | The operations, grouped by tag, a method each. |
| `src/<module>/types.py` | A `TypedDict` for each schema. |
| `src/<module>/_core.py` | The runtime, the same file in every Python SDK we generate. |
| `src/<module>/py.typed` | The marker that tells type checkers the package is typed. |
| `README.md`, `GENERATION.md`, `CHANGELOG.md`, `LICENSE` | As in the TypeScript package. |

The code is laid out as `ruff format` lays it out, so `ruff format --check` passes, and it type-checks under pyright's strict mode.

## Clients

The client is named from `clientName`, and its async twin has `Async` in front: `Acme` and `AsyncAcme`. Both take the same arguments. Credentials are passed in, never read from the environment. Pass `http_client=` to use your own `httpx.Client`, and close a client with `close()`, `aclose()` for the async one, or a `with` block.

## Retries, errors and responses

- Connection errors, timeouts, `408`, `429` and `5xx` are retried with backoff, and `Retry-After` is honoured. `POST` and `PATCH` are retried only with an idempotency key: `idempotency_key=` on a call, or one made for you when the operation declares an `Idempotency-Key` header. Set `max_retries` and `timeout` on the client or per call.
- A response outside `2xx` raises an `APIError` with `status_code`, `headers`, `body` and `request_id`, as the same classes the TypeScript package throws. A network failure raises `APIConnectionError`, a timeout `APITimeoutError`.
- Methods return the parsed JSON body, typed by the `TypedDict`s. Every method has a `…_with_response` sibling that returns `(data, response)`, the `httpx.Response`.

## Where this comes from

- `app/sdk/_lib/python/emit.ts`
- `app/sdk/_lib/python/types.ts`
- `app/sdk/_lib/python/layout.ts`
- `app/sdk/_lib/python/runtime/_core.py`
- `tests/fixtures/sdk/petstore/expected-python/README.md`