Metadata-Version: 2.4
Name: pulsight
Version: 0.1.0
Summary: Official Python client for the Pulsight API
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# pulsight (Python)

Official Python client for the [Pulsight](https://pulsight.xyz) public API.

## Layout

- `pulsight_api_client/` — protocol core generated by [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client) from `sdks/openapi/public.json`. **Never hand-edited**, regenerated by `make sdk-python`.
- `pulsight/` — the handwritten ergonomic layer: api-token auth, 429 retry, typed errors. Depends only on `httpx`.

## Generate

From the repo root:

```sh
make sdk-python
```

Or directly:

```sh
pipx run openapi-python-client generate \
  --path sdks/openapi/public.json \
  --config sdks/python/openapi-python-client-config.yaml \
  --meta none --output-path sdks/python/pulsight_api_client --overwrite
```

## Usage

```python
import pulsight
from pulsight_api_client import AuthenticatedClient
from pulsight_api_client.api.data import list_traders

# Hand the authenticated httpx client to the generated AuthenticatedClient.
http = pulsight.build_client("pk_live_…")  # api token from the settings UI
client = AuthenticatedClient(base_url=pulsight.DEFAULT_BASE_URL, token="").set_httpx_client(http)

resp = list_traders.sync_detailed(client=client)
pulsight.raise_for_response(resp.parsed and resp or resp)  # see note below
print("credits left:", pulsight.credits_remaining(resp))
```

> The exact generated call signatures depend on the spec's operation ids;
> `make sdk-python` emits them under `pulsight_api_client/api/*`. The
> ergonomic helpers (`raise_for_response`, `credits_remaining`) take an
> `httpx.Response`, which the generated `*_detailed` calls expose.

## Error mapping

| HTTP | Exception |
|---|---|
| 402 `CREDIT_EXHAUSTED` | `CreditExhaustedError(pool)` |
| 429 | `RateLimitedError(retry_after)` (idempotent GETs auto-retry) |
| 403 (missing scope) | `MissingScopeError(message)` |
| other non-2xx | `APIError(status_code, body)` |

All inherit `PulsightError`.
