deeptick 0.1.0__py3-none-any.whl

deeptick/__init__.py

@@ -0,0 +1,6 @@
+"""DeepTick Python SDK."""
+
+from .client import CachedClient, DeepTickAPIError, DeepTickClient
+
+__all__ = ["CachedClient", "DeepTickAPIError", "DeepTickClient"]
+

deeptick/client.py

@@ -0,0 +1,450 @@
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+import shutil
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Any, Iterable
+from urllib.parse import quote
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+import requests
+
+DEFAULT_BASE_URL = "https://deeptick.dev"
+USER_AGENT = "deeptick-python/0.1.0"
+DEFAULT_CACHE_DIR = Path(os.path.expanduser("~/.deeptick/cache"))
+DateLike = str | date | datetime
+
+
+class DeepTickAPIError(RuntimeError):
+    """Raised when the DeepTick API returns an unexpected HTTP error."""
+
+
+def _normalize_base_url(base_url: str | None) -> str:
+    value = (base_url or DEFAULT_BASE_URL).rstrip("/")
+    if value.endswith("/v1"):
+        value = value[:-3]
+    return value.rstrip("/")
+
+
+def _looks_like_url(value: str | None) -> bool:
+    return bool(value and value.startswith(("http://", "https://")))
+
+
+def _resolve_cached_client_args(
+    api_key: str | None,
+    base_url: str,
+) -> tuple[str | None, str]:
+    if _looks_like_url(api_key):
+        if base_url == DEFAULT_BASE_URL:
+            return None, api_key or DEFAULT_BASE_URL
+        return base_url, api_key or DEFAULT_BASE_URL
+    return api_key, base_url
+
+
+def _coerce_date(value: DateLike) -> date:
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    try:
+        return datetime.strptime(value, "%Y-%m-%d").date()
+    except ValueError as exc:
+        raise ValueError(f"expected date as YYYY-MM-DD, got {value!r}") from exc
+
+
+def _date_range(start: DateLike, end: DateLike | None) -> list[str]:
+    first = _coerce_date(start)
+    last = _coerce_date(end or start)
+    if last < first:
+        raise ValueError("end date must be on or after start date")
+
+    out: list[str] = []
+    current = first
+    while current <= last:
+        out.append(current.isoformat())
+        current += timedelta(days=1)
+    return out
+
+
+def _columns_param(columns: Iterable[str] | None) -> str | None:
+    if columns is None:
+        return None
+    selected = [col for col in columns if col]
+    return ",".join(selected) if selected else None
+
+
+def _empty_table() -> pa.Table:
+    return pa.table({})
+
+
+def _resolve_date_args(
+    start: DateLike | None,
+    end: DateLike | None,
+    *,
+    start_date: DateLike | None = None,
+    end_date: DateLike | None = None,
+) -> tuple[DateLike, DateLike | None]:
+    if (
+        start is not None
+        and start_date is not None
+        and _coerce_date(start) != _coerce_date(start_date)
+    ):
+        raise ValueError("pass either start or start_date, not both")
+    if (
+        end is not None
+        and end_date is not None
+        and _coerce_date(end) != _coerce_date(end_date)
+    ):
+        raise ValueError("pass either end or end_date, not both")
+
+    resolved_start = start if start is not None else start_date
+    if resolved_start is None:
+        raise TypeError("missing required date: start")
+    return resolved_start, end if end is not None else end_date
+
+
+class DeepTickClient:
+    """HTTP client for the DeepTick `/v1/*` REST API.
+
+    Args:
+        api_key: API key sent in the `X-API-Key` header.
+        base_url: API origin, with or without a trailing `/v1`.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        session: requests.Session | None = None,
+        timeout: int = 120,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("DEEPTICK_API_KEY") or ""
+        self.base_url = _normalize_base_url(base_url)
+        self.session = session or requests.Session()
+        self.timeout = timeout
+
+    def catalog(self, exchange: str | None = None) -> dict[str, Any]:
+        """Return the downloadable dataset catalog."""
+        params = {"exchange": exchange} if exchange else None
+        return self._json("/v1/catalog", params=params)
+
+    def entitlements(self) -> dict[str, Any]:
+        """Return the presented API key's download entitlements."""
+        return self._json("/v1/entitlements")
+
+    def download(
+        self,
+        exchange: str,
+        data_type: str,
+        symbol: str,
+        date: DateLike,
+        dest: str | os.PathLike[str],
+        *,
+        columns: Iterable[str] | None = None,
+        format: str = "parquet",
+    ) -> Path:
+        """Download one daily partition to `dest` and return the final path."""
+        target = Path(dest)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        tmp = target.with_name(f"{target.name}.part")
+
+        response = self._request(
+            "GET",
+            self._data_path(exchange, data_type, symbol, date),
+            params=self._data_params(format=format, columns=columns),
+            stream=True,
+        )
+        self._raise_for_status(response)
+        with tmp.open("wb") as fh:
+            for chunk in response.iter_content(chunk_size=256 * 1024):
+                if chunk:
+                    fh.write(chunk)
+        tmp.replace(target)
+        return target
+
+    def load_trades(
+        self,
+        exchange: str,
+        symbol: str,
+        start: DateLike | None = None,
+        end: DateLike | None = None,
+        *,
+        start_date: DateLike | None = None,
+        end_date: DateLike | None = None,
+        columns: Iterable[str] | None = None,
+    ) -> pa.Table:
+        """Load trade data over an inclusive date range as a PyArrow table."""
+        return self.load(
+            "trades",
+            exchange,
+            symbol,
+            start,
+            end,
+            start_date=start_date,
+            end_date=end_date,
+            columns=columns,
+        )
+
+    def load(
+        self,
+        data_type: str,
+        exchange: str,
+        symbol: str,
+        start: DateLike | None = None,
+        end: DateLike | None = None,
+        *,
+        start_date: DateLike | None = None,
+        end_date: DateLike | None = None,
+        columns: Iterable[str] | None = None,
+    ) -> pa.Table:
+        """Load any DeepTick data type over an inclusive date range."""
+        start, end = _resolve_date_args(
+            start,
+            end,
+            start_date=start_date,
+            end_date=end_date,
+        )
+        tables = [
+            table
+            for day in _date_range(start, end)
+            if (table := self._load_day(exchange, data_type, symbol, day, columns=columns))
+            is not None
+        ]
+        if not tables:
+            return _empty_table()
+        return pa.concat_tables(tables, promote_options="default")
+
+    def _load_day(
+        self,
+        exchange: str,
+        data_type: str,
+        symbol: str,
+        day: str,
+        *,
+        columns: Iterable[str] | None = None,
+    ) -> pa.Table | None:
+        response = self._request(
+            "GET",
+            self._data_path(exchange, data_type, symbol, day),
+            params=self._data_params(format="parquet", columns=columns),
+        )
+        if response.status_code == 404:
+            return None
+        self._raise_for_status(response)
+        return pq.read_table(io.BytesIO(response.content))
+
+    def _json(self, path: str, *, params: dict[str, str] | None = None) -> dict[str, Any]:
+        response = self._request("GET", path, params=params)
+        self._raise_for_status(response)
+        data = response.json()
+        if not isinstance(data, dict):
+            raise DeepTickAPIError(f"expected object response from {path}")
+        return data
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        stream: bool = False,
+    ) -> requests.Response:
+        return self.session.request(
+            method,
+            f"{self.base_url}{path}",
+            headers=self._headers(),
+            params=params,
+            timeout=self.timeout,
+            stream=stream,
+        )
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"User-Agent": USER_AGENT}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        return headers
+
+    @staticmethod
+    def _raise_for_status(response: requests.Response) -> None:
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as exc:
+            detail = response.text[:500] if response.text else response.reason
+            message = f"DeepTick API returned HTTP {response.status_code}: {detail}"
+            raise DeepTickAPIError(message) from exc
+
+    @staticmethod
+    def _data_path(
+        exchange: str,
+        data_type: str,
+        symbol: str,
+        day: DateLike,
+    ) -> str:
+        return (
+            "/v1/data/"
+            f"{quote(exchange, safe='')}/"
+            f"{quote(data_type, safe='')}/"
+            f"{quote(symbol, safe='')}/"
+            f"{quote(_coerce_date(day).isoformat(), safe='')}"
+        )
+
+    @staticmethod
+    def _data_params(
+        *,
+        format: str = "parquet",
+        columns: Iterable[str] | None = None,
+    ) -> dict[str, str]:
+        params = {"format": format}
+        if selected := _columns_param(columns):
+            params["columns"] = selected
+        return params
+
+
+class CachedClient(DeepTickClient):
+    """DeepTick client with local daily parquet caching.
+
+    The preferred positional order matches `DeepTickClient(api_key, base_url)`.
+    Existing site examples that pass `base_url` first or use keywords are also
+    accepted.
+
+    ```python
+    from deeptick import CachedClient
+    client = CachedClient(api_key="dtk_your_key")
+    ```
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        cache_dir: str | os.PathLike[str] = DEFAULT_CACHE_DIR,
+        max_workers: int = 8,
+        session: requests.Session | None = None,
+        timeout: int = 120,
+    ) -> None:
+        api_key, base_url = _resolve_cached_client_args(api_key, base_url)
+        super().__init__(api_key=api_key, base_url=base_url, session=session, timeout=timeout)
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.max_workers = max_workers
+        self.cache_hits = 0
+        self.cache_misses = 0
+        self.bytes_downloaded = 0
+        self.bytes_from_cache = 0
+
+    def load(
+        self,
+        data_type: str,
+        exchange: str,
+        symbol: str,
+        start: DateLike | None = None,
+        end: DateLike | None = None,
+        *,
+        start_date: DateLike | None = None,
+        end_date: DateLike | None = None,
+        columns: Iterable[str] | None = None,
+    ) -> pa.Table:
+        start, end = _resolve_date_args(start, end, start_date=start_date, end_date=end_date)
+        days = _date_range(start, end)
+        if len(days) == 1:
+            table = self._load_day_cached(exchange, data_type, symbol, days[0], columns=columns)
+            return table if table is not None else _empty_table()
+
+        tables: list[tuple[str, pa.Table]] = []
+        with ThreadPoolExecutor(max_workers=min(self.max_workers, len(days))) as pool:
+            futures = {
+                pool.submit(
+                    self._load_day_cached,
+                    exchange,
+                    data_type,
+                    symbol,
+                    day,
+                    columns=columns,
+                ): day
+                for day in days
+            }
+            for future in as_completed(futures):
+                day = futures[future]
+                table = future.result()
+                if table is not None:
+                    tables.append((day, table))
+
+        if not tables:
+            return _empty_table()
+        tables.sort(key=lambda item: item[0])
+        return pa.concat_tables([table for _, table in tables], promote_options="default")
+
+    def cache_stats(self) -> dict[str, Any]:
+        """Return cache counters and current disk footprint."""
+        files = list(self.cache_dir.rglob("*.parquet"))
+        total_bytes = sum(path.stat().st_size for path in files)
+        total_requests = self.cache_hits + self.cache_misses
+        total_bytes_seen = self.bytes_from_cache + self.bytes_downloaded
+        return {
+            "cache_dir": str(self.cache_dir),
+            "cache_hits": self.cache_hits,
+            "cache_misses": self.cache_misses,
+            "hit_rate_pct": round(self.cache_hits / max(total_requests, 1) * 100, 1),
+            "cached_files": len(files),
+            "cache_size_mb": round(total_bytes / (1024 * 1024), 2),
+            "bytes_downloaded": self.bytes_downloaded,
+            "bytes_from_cache": self.bytes_from_cache,
+            "bandwidth_saved_pct": round(
+                self.bytes_from_cache / max(total_bytes_seen, 1) * 100,
+                1,
+            ),
+        }
+
+    def clear_cache(self) -> None:
+        """Remove all locally cached parquet files."""
+        shutil.rmtree(self.cache_dir, ignore_errors=True)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _load_day_cached(
+        self,
+        exchange: str,
+        data_type: str,
+        symbol: str,
+        day: str,
+        *,
+        columns: Iterable[str] | None = None,
+    ) -> pa.Table | None:
+        cache_path = self._cache_path(exchange, data_type, symbol, day, columns=columns)
+        if cache_path.exists() and cache_path.stat().st_size > 0:
+            self.cache_hits += 1
+            self.bytes_from_cache += cache_path.stat().st_size
+            return pq.read_table(cache_path)
+
+        self.cache_misses += 1
+        table = super()._load_day(exchange, data_type, symbol, day, columns=columns)
+        if table is None:
+            return None
+
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = cache_path.with_name(f"{cache_path.name}.part")
+        pq.write_table(table, tmp, compression="zstd")
+        tmp.replace(cache_path)
+        self.bytes_downloaded += cache_path.stat().st_size
+        return table
+
+    def _cache_path(
+        self,
+        exchange: str,
+        data_type: str,
+        symbol: str,
+        day: str,
+        *,
+        columns: Iterable[str] | None = None,
+    ) -> Path:
+        safe_symbol = symbol.replace("/", "-").replace(":", "-")
+        suffix = ""
+        if selected := _columns_param(columns):
+            suffix = "_" + hashlib.md5(selected.encode("utf-8")).hexdigest()[:8]
+        return self.cache_dir / exchange / data_type / safe_symbol / f"{day}{suffix}.parquet"

deeptick/py.typed

@@ -0,0 +1 @@
+

deeptick-0.1.0.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.5
+Name: deeptick
+Version: 0.1.0
+Summary: DeepTick Python SDK for authenticated market data downloads
+Project-URL: Homepage, https://deeptick.lacertalabs.xyz
+Project-URL: Repository, https://github.com/deeptick/deeptick
+Project-URL: Documentation, https://deeptick.lacertalabs.xyz/docs
+Author: DeepTick
+License: MIT
+Keywords: crypto,deeptick,market-data,parquet,pyarrow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: pyarrow>=17.0
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DeepTick Python SDK
+
+```python
+from deeptick import CachedClient
+
+client = CachedClient("dtk_your_key", "https://deeptick.dev")
+trades = client.load_trades("lighter", "BTC-USD", "2026-07-08", "2026-07-08")
+```
+
+The SDK uses the public DeepTick REST API under `/v1/*` and sends credentials
+with the `X-API-Key` header.
+
+Surface:
+
+- `DeepTickClient(api_key, base_url="https://deeptick.dev")`
+- `load_trades(exchange, symbol, start, end)` returns a `pyarrow.Table`
+- `download(exchange, data_type, symbol, date, dest)` streams one partition to disk
+- `entitlements()` and `catalog(exchange=None)` return API metadata
+- `CachedClient` adds local Parquet caching under `~/.deeptick/cache`

deeptick-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+deeptick/__init__.py,sha256=Js_bx76_d__OwIZWeriYLwCfMKsswI6QmZDmBjNkVIU,162
+deeptick/client.py,sha256=ueqj5M7LtP8XhC-CbwUGs2TGZ6gy9low-MZK9egfx7I,14555
+deeptick/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+deeptick-0.1.0.dist-info/METADATA,sha256=9HjpHMNBRiJU_Ph-2et_8A0lyFTNj3M8xI86ulRhqzA,1618
+deeptick-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+deeptick-0.1.0.dist-info/RECORD,,

deeptick-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any