polaris-data 0.1.0__tar.gz

polaris_data-0.1.0/.context/attachments/PR instructions.md

@@ -0,0 +1,19 @@
+The user likes the current state of the code.
+
+There are 14 uncommitted changes.
+The current branch is HilliamT/python-sdk-scaffold.
+The target branch is origin/main.
+
+There is no upstream branch yet.
+The user requested a PR.
+
+Follow these steps to create a PR:
+
+- If you have any skills related to creating PRs, invoke them now. Instructions there should take precedence over these instructions.
+- Run `git diff` to review uncommitted changes
+- Commit them. Follow any instructions the user gave you about writing commit messages.
+- Push to origin.
+- Use `git diff origin/main...` to review the PR diff
+- Use `gh pr create --base main` to create a PR onto the target branch. Keep the title under 80 characters. Keep the description under five sentences, unless the user instructed you otherwise. Describe not just changes made in this session but ALL changes in the workspace diff.
+
+If any of these steps fail, ask the user for help.

polaris_data-0.1.0/.git

@@ -0,0 +1 @@
+gitdir: /Users/hilliamtung/Documents/GitHub/polaris-py/.git/worktrees/stockholm

polaris_data-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.pyc

polaris_data-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: polaris-data
+Version: 0.1.0
+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
+Description-Content-Type: text/markdown
+
+# polaris-py
+
+Python SDK for the Polaris API, optimized for notebook workflows and trading scripts.
+
+## Install (uv)
+
+```bash
+uv sync --group dev
+```
+
+Useful commands:
+
+```bash
+uv run python
+uv lock
+```
+
+## Quickstart
+
+```python
+from polaris_data import PolarisClient
+
+with PolarisClient.new("pk_live_your_key") as client:
+    exchanges = client.exchanges()
+    assets = client.assets(exchanges[0])
+
+    trades = client.collect_all_trades(
+        exchange=exchanges[0],
+        asset=assets[0],
+        from_="2024-01-01T00:00:00Z",
+        to="2024-01-01T01:00:00Z",
+        limit=500,
+    )
+
+    print(f"Loaded {len(trades)} trades")
+```
+
+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)`
+- `dataset_size(exchange, asset, from_, to)`
+- `catalog()`
+- `dataset_preview(..., standard=False)`
+- `ohlcv_preview(..., interval, limit=None, format=None)`
+
+Authenticated endpoints:
+
+- `dataset_download_url(..., standard=False)`
+- `trades_page(..., limit=1000, cursor=None)`
+- `iter_trades(...)`
+- `collect_all_trades(...)`
+- `stream_events(..., standard=False)`
+- `collect_events(..., standard=False)`
+- `iter_ohlcv(..., interval)`
+- `ohlcv(..., interval, format=None)`
+
+## Error handling
+
+```python
+from polaris_data import PolarisClient, RateLimitedError, UnauthorizedError
+
+client = PolarisClient.anonymous()
+
+try:
+    client.collect_events("binance", "BTC-USDT", "2024-01-01T00:00:00Z", "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
+```

polaris_data-0.1.0/README.md

@@ -0,0 +1,92 @@
+# polaris-py
+
+Python SDK for the Polaris API, optimized for notebook workflows and trading scripts.
+
+## Install (uv)
+
+```bash
+uv sync --group dev
+```
+
+Useful commands:
+
+```bash
+uv run python
+uv lock
+```
+
+## Quickstart
+
+```python
+from polaris_data import PolarisClient
+
+with PolarisClient.new("pk_live_your_key") as client:
+    exchanges = client.exchanges()
+    assets = client.assets(exchanges[0])
+
+    trades = client.collect_all_trades(
+        exchange=exchanges[0],
+        asset=assets[0],
+        from_="2024-01-01T00:00:00Z",
+        to="2024-01-01T01:00:00Z",
+        limit=500,
+    )
+
+    print(f"Loaded {len(trades)} trades")
+```
+
+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)`
+- `dataset_size(exchange, asset, from_, to)`
+- `catalog()`
+- `dataset_preview(..., standard=False)`
+- `ohlcv_preview(..., interval, limit=None, format=None)`
+
+Authenticated endpoints:
+
+- `dataset_download_url(..., standard=False)`
+- `trades_page(..., limit=1000, cursor=None)`
+- `iter_trades(...)`
+- `collect_all_trades(...)`
+- `stream_events(..., standard=False)`
+- `collect_events(..., standard=False)`
+- `iter_ohlcv(..., interval)`
+- `ohlcv(..., interval, format=None)`
+
+## Error handling
+
+```python
+from polaris_data import PolarisClient, RateLimitedError, UnauthorizedError
+
+client = PolarisClient.anonymous()
+
+try:
+    client.collect_events("binance", "BTC-USDT", "2024-01-01T00:00:00Z", "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
+```

polaris_data-0.1.0/examples/basic_usage.py

@@ -0,0 +1,18 @@
+"""Minimal example for script and notebook workflows."""
+
+from polaris_data import PolarisClient
+
+
+with PolarisClient.new("pk_live_your_key") as client:
+    exchanges = client.exchanges()
+    print("Exchanges:", exchanges)
+
+    bars = client.ohlcv(
+        exchange="binance",
+        asset="BTC-USDT",
+        from_="2024-01-01T00:00:00Z",
+        to="2024-01-01T01:00:00Z",
+        interval="1m",
+    )
+
+    print(f"Downloaded {len(bars)} bars")

polaris_data-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "polaris-data"
+version = "0.1.0"
+description = "Python SDK for the Polaris market data API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "Polaris" }
+]
+dependencies = [
+  "httpx>=0.27.0"
+]
+keywords = ["polaris", "market-data", "trading", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+
+[project.urls]
+Homepage = "https://polaris.supply"
+Repository = "https://github.com/polaris-supply"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0.0"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/polaris_data"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

polaris_data-0.1.0/src/polaris_data/__init__.py

@@ -0,0 +1,21 @@
+"""Python SDK for the Polaris market data API."""
+
+from .client import PolarisClient
+from .errors import (
+    NotFoundError,
+    PolarisError,
+    RateLimitedError,
+    StreamDecodeError,
+    UnauthorizedError,
+)
+
+__all__ = [
+    "NotFoundError",
+    "PolarisClient",
+    "PolarisError",
+    "RateLimitedError",
+    "StreamDecodeError",
+    "UnauthorizedError",
+]
+
+__version__ = "0.1.0"