Metadata-Version: 2.4
Name: polaris-data
Version: 0.3.1
Summary: Python SDK for the Polaris market data API
Project-URL: Homepage, https://polaris.supply
Project-URL: Repository, https://github.com/polaris-supply
Author: Polaris
License: MIT
Keywords: market-data,polaris,sdk,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: zstandard>=0.23.0
Description-Content-Type: text/markdown

# polaris-py

Python SDK for the Polaris API, optimized for notebook workflows and trading scripts.
Documentation can be found at https://polaris.supply/docs

## Install (uv)

```bash
uv sync --group dev
```

Useful commands:

```bash
uv run python
uv lock
```

## Quickstart

```python
from polaris_data import PolarisClient

with PolarisClient(api_key="polaris_key_your_key") as client:
    row_count = 0
    for row in client.replay(
        exchange="binance",
        asset="BTC-USDT",
        from_="2024-01-01T00:00:00Z",
        to="2024-01-01T01:00:00Z",
    ):
        row_count += 1

    print(f"Replayed {row_count} rows")
```

If `api_key` is omitted, the client reads `POLARIS_API_KEY` from the environment.

## Supported input time types

Methods that take `from_` and `to` accept:

- ISO 8601 strings (`"2024-01-01T00:00:00Z"`)
- `datetime.datetime`
- `datetime.date`
- Unix epoch microseconds (`int`/`float`)

## Methods

Open endpoints:

- `health()`
- `exchanges()`
- `assets(exchange=...)`
- `timerange(exchange=..., asset=...)`
- `catalog()`

Authenticated endpoints:

- `replay(exchange=..., asset=..., from_=..., to=..., standard=True)` (iterator over `/events` or `/raw`)
- `trades(exchange=..., asset=..., from_=..., to=..., limit=1000)` (collects all pages)
- `events(exchange=..., asset=..., from_=..., to=..., limit=1000)` (collects all pages)
- `raw(exchange=..., asset=..., from_=..., to=..., limit=1000)` (collects all pages)
- `ohlcv(exchange=..., asset=..., from_=..., to=..., interval=..., format=None)`

For event/data endpoints, `standard=True` is the default. Pass `standard=False` when you explicitly need raw schema payloads.

## Dataset replay (recommended)

For row-by-row iteration without managing file paths, use `replay(...)`:

```python
from polaris_data import PolarisClient

with PolarisClient(api_key="polaris_key_your_key") as client:
    for row in client.replay(
        exchange="binance",
        asset="BTC-USDT",
        from_="2024-01-01T00:00:00Z",
        to="2024-01-01T01:00:00Z",
    ):
        print(row)
```

`replay(...)` checks the local replay cache first, then fetches paginated rows and caches them as NDJSON if needed.
Replay cache is enabled by default and stored under:

- macOS: `~/Library/Caches/polaris/datasets/replay`
- Linux: `~/.cache/polaris/datasets/replay`
- Windows: `%LOCALAPPDATA%\\polaris\\datasets\\replay`

Set `POLARIS_DATASET_DOWNLOAD_DIR` to override the base directory globally.
Use `replay_cache_enabled=False` to disable caching, or `replay_cache_dir=...` to set a custom path.

## Error handling

```python
from polaris_data import PolarisClient, RateLimitedError, UnauthorizedError

client = PolarisClient()

try:
    client.replay(
        exchange="binance",
        asset="BTC-USDT",
        from_="2024-01-01T00:00:00Z",
        to="2024-01-01T01:00:00Z",
    )
except UnauthorizedError:
    print("API key is required")
except RateLimitedError as err:
    print(f"Rate limited. Reset at: {err.reset_at}")
```

## Tests

```bash
uv run pytest
```
