tessera-api 0.1.0__py3-none-any.whl

tessera/__init__.py

@@ -0,0 +1,68 @@
+"""Tessera API client — Hyperliquid datasets straight into Polars & DuckDB.
+
+Quickstart:
+    >>> import tessera
+    >>> client = tessera.TesseraClient()          # reads $TESSERA_API_KEY
+    >>> df = client.read("gold_ohlcv_1m", "BTC", "2025-09")
+
+See https://tesseralytics.dev for an API key and dataset reference.
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .async_client import AsyncTesseraClient
+from .client import TesseraClient
+from .errors import (
+    AuthenticationError,
+    BadRequestError,
+    ConfigurationError,
+    ForbiddenError,
+    InternalServerError,
+    MissingDependencyError,
+    NetworkError,
+    NotFoundError,
+    PresignExpiredError,
+    ServiceUnavailableError,
+    TesseraAPIError,
+    TesseraError,
+)
+from .models import (
+    DatasetsResponse,
+    DatasetSummary,
+    DownloadResponse,
+    MonthRange,
+    MonthSpan,
+    Partition,
+    PartitionRef,
+    PartitionsResponse,
+)
+
+__all__ = [
+    "AsyncTesseraClient",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConfigurationError",
+    "DatasetSummary",
+    # models & helpers
+    "DatasetsResponse",
+    "DownloadResponse",
+    "ForbiddenError",
+    "InternalServerError",
+    "MissingDependencyError",
+    "MonthRange",
+    "MonthSpan",
+    "NetworkError",
+    "NotFoundError",
+    "Partition",
+    "PartitionRef",
+    "PartitionsResponse",
+    "PresignExpiredError",
+    "ServiceUnavailableError",
+    "TesseraAPIError",
+    # clients
+    "TesseraClient",
+    # errors
+    "TesseraError",
+    "__version__",
+]

tessera/_base.py

@@ -0,0 +1,81 @@
+"""Transport-agnostic plumbing shared by the sync and async clients.
+
+The two clients differ only in how they *await* I/O; everything else — URL
+construction, header building, error mapping, retry decisions — lives here so
+there is a single source of truth.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import quote
+
+import httpx
+
+from .config import RETRYABLE_STATUSES, ClientConfig
+from .errors import error_from_response
+
+
+def _seg(value: str) -> str:
+    """URL-encode a single path segment (no slashes survive)."""
+    return quote(value, safe="")
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedRequest:
+    """A resolved HTTP request: path + query params, ready to send."""
+
+    path: str
+    params: dict[str, str]
+
+
+def datasets_request() -> PreparedRequest:
+    return PreparedRequest("/v1/datasets", {})
+
+
+def partitions_request(asset: str, coin: str | None, month: str | None) -> PreparedRequest:
+    params: dict[str, str] = {}
+    if coin is not None:
+        params["coin"] = coin
+    if month is not None:
+        params["month"] = month
+    return PreparedRequest(f"/v1/datasets/{_seg(asset)}", params)
+
+
+def download_request(asset: str, coin: str, month: str) -> PreparedRequest:
+    path = f"/v1/datasets/{_seg(asset)}/{_seg(coin)}/{_seg(month)}/download"
+    return PreparedRequest(path, {})
+
+
+def parse_retry_after(response: httpx.Response) -> float | None:
+    """Parse the ``Retry-After`` header (seconds form only) if present."""
+    raw = response.headers.get("retry-after")
+    if raw is None:
+        return None
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
+def should_retry(status_code: int) -> bool:
+    return status_code in RETRYABLE_STATUSES
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Raise the mapped :class:`TesseraAPIError` for a non-2xx response."""
+    if response.is_success:
+        return
+    raise error_from_response(response.status_code, response.content)
+
+
+def build_httpx_kwargs(config: ClientConfig) -> dict[str, object]:
+    """Shared constructor kwargs for both ``httpx.Client`` and ``AsyncClient``."""
+    return {
+        "base_url": config.base_url,
+        "headers": config.auth_headers(),
+        "timeout": config.timeout,
+        # The download endpoint 302-redirects to the presigned URL; we want the
+        # JSON body (with expiry), so never auto-follow.
+        "follow_redirects": False,
+    }

tessera/_generated/__init__.py

@@ -0,0 +1 @@
+"""Machine-generated schema models. Do not edit by hand — see ``make codegen``."""

tessera/_generated/models.py

@@ -0,0 +1,85 @@
+# AUTO-GENERATED from openapi.json by datamodel-code-generator — DO NOT EDIT. Run: make codegen
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+
+class DownloadResponse(BaseModel):
+    expires_at: Annotated[
+        str, Field(description='RFC3339 timestamp at which the URL expires.')
+    ]
+    url: Annotated[
+        str, Field(description='Presigned Tigris URL for the parquet object.')
+    ]
+
+
+class ErrorBody(BaseModel):
+    """
+    The error response body. Every error variant serialises to this shape —
+    a single machine-readable `error` code. Declared as a real struct (rather
+    than the inline `json!` below) only so it can be referenced as a response
+    `body` in the OpenAPI spec; `into_response` still emits the same JSON.
+    """
+
+    error: Annotated[
+        str,
+        Field(
+            description='Machine-readable error code, e.g. `not_found`, `unauthorized`.',
+            examples=['not_found'],
+        ),
+    ]
+
+
+class MonthRange(BaseModel):
+    earliest: Annotated[
+        str | None, Field(description='Earliest partition month (`YYYY-MM`), if any.')
+    ] = None
+    latest: Annotated[
+        str | None, Field(description='Latest partition month (`YYYY-MM`), if any.')
+    ] = None
+
+
+class Partition(BaseModel):
+    coin: Annotated[
+        str, Field(description='Coin symbol, e.g. `BTC`.', examples=['BTC'])
+    ]
+    modified_at: Annotated[
+        str | None, Field(description='RFC3339 timestamp of the last write, if known.')
+    ] = None
+    month: Annotated[
+        str, Field(description='Partition month, `YYYY-MM`.', examples=['2025-09'])
+    ]
+    size_bytes: Annotated[int, Field(description='Parquet object size in bytes.')]
+
+
+class PartitionsResponse(BaseModel):
+    asset: Annotated[str, Field(description='Dataset name the partitions belong to.')]
+    generated_at: Annotated[
+        str, Field(description='RFC3339 timestamp the catalog manifest was generated.')
+    ]
+    partitions: list[Partition]
+
+
+class DatasetSummary(BaseModel):
+    coins: Annotated[list[str], Field(description='Distinct coins present, sorted.')]
+    months: MonthRange
+    name: Annotated[
+        str,
+        Field(
+            description='Dataset name, e.g. `gold_ohlcv_1m`.',
+            examples=['gold_ohlcv_1m'],
+        ),
+    ]
+    partition_count: Annotated[
+        int, Field(description='Number of partitions visible to the caller.', ge=0)
+    ]
+
+
+class DatasetsResponse(BaseModel):
+    datasets: list[DatasetSummary]
+    generated_at: Annotated[
+        str, Field(description='RFC3339 timestamp the catalog manifest was generated.')
+    ]

tessera/_resolver.py

@@ -0,0 +1,41 @@
+"""Concurrent presigned-URL resolution.
+
+Each ``(asset, coin, month)`` partition needs its own short-lived presigned URL,
+minted via the download endpoint. For multi-partition reads we resolve them
+concurrently — a thread pool for the sync client, ``asyncio.gather`` for async.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Sequence
+from concurrent.futures import ThreadPoolExecutor
+
+from .models import PartitionRef
+
+ResolvedPartition = tuple[PartitionRef, str]
+
+_MAX_WORKERS = 8
+
+
+def resolve_sync(
+    fetch_url: Callable[[PartitionRef], str],
+    refs: Sequence[PartitionRef],
+) -> list[ResolvedPartition]:
+    """Resolve presigned URLs for ``refs`` concurrently, preserving order."""
+    if len(refs) == 1:
+        ref = refs[0]
+        return [(ref, fetch_url(ref))]
+    workers = min(_MAX_WORKERS, len(refs))
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        urls = list(pool.map(fetch_url, refs))
+    return list(zip(refs, urls, strict=True))
+
+
+async def resolve_async(
+    fetch_url: Callable[[PartitionRef], Awaitable[str]],
+    refs: Sequence[PartitionRef],
+) -> list[ResolvedPartition]:
+    """Resolve presigned URLs for ``refs`` concurrently, preserving order."""
+    urls = await asyncio.gather(*(fetch_url(ref) for ref in refs))
+    return list(zip(refs, urls, strict=True))

tessera/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tessera/async_client.py

@@ -0,0 +1,191 @@
+"""Asynchronous Tessera API client."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from types import TracebackType
+from typing import TYPE_CHECKING
+
+import httpx
+
+from . import _base, _resolver
+from .config import DEFAULT_BASE_URL, ClientConfig, backoff_delay, resolve_api_key
+from .errors import NetworkError
+from .models import (
+    Coins,
+    DatasetsResponse,
+    DownloadResponse,
+    Months,
+    PartitionRef,
+    PartitionsResponse,
+)
+from .readers import duckdb as _duckdb_reader
+from .readers import polars as _polars_reader
+from .readers._common import expand_refs, frame_to_pandas
+
+if TYPE_CHECKING:
+    import duckdb
+    import pandas
+    import polars as pl
+
+__all__ = ["AsyncTesseraClient"]
+
+
+class AsyncTesseraClient:
+    """An asyncio-native client for the Tessera API.
+
+    Mirrors :class:`~tessera.TesseraClient` with ``await``. Parquet reads (which
+    are CPU/IO-bound and synchronous in the engines) run in a worker thread so
+    they never block the event loop.
+
+    Example:
+        >>> async with AsyncTesseraClient() as client:
+        ...     df = await client.read("gold_ohlcv_1m", "BTC", "2025-09")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.config = ClientConfig(
+            api_key=resolve_api_key(api_key),
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        if http_client is not None:
+            self._http = http_client
+            self._owns_http = False
+        else:
+            self._http = httpx.AsyncClient(**_base.build_httpx_kwargs(self.config))  # type: ignore[arg-type]
+            self._owns_http = True
+
+    # -- lifecycle ---------------------------------------------------------
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncTesseraClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    # -- transport ---------------------------------------------------------
+    async def _request(self, prepared: _base.PreparedRequest) -> httpx.Response:
+        for attempt in range(self.config.max_retries + 1):
+            last = attempt == self.config.max_retries
+            try:
+                response = await self._http.get(prepared.path, params=prepared.params or None)
+            except httpx.TransportError as exc:
+                if last:
+                    raise NetworkError(f"network error contacting Tessera: {exc}") from exc
+                await asyncio.sleep(backoff_delay(attempt, None))
+                continue
+            if not last and _base.should_retry(response.status_code):
+                await asyncio.sleep(backoff_delay(attempt, _base.parse_retry_after(response)))
+                continue
+            _base.raise_for_status(response)
+            return response
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    # -- metadata endpoints ------------------------------------------------
+    async def datasets(self) -> DatasetsResponse:
+        """List every dataset visible to your plan."""
+        response = await self._request(_base.datasets_request())
+        return DatasetsResponse.model_validate_json(response.content)
+
+    async def partitions(
+        self,
+        asset: str,
+        *,
+        coin: str | None = None,
+        month: str | None = None,
+    ) -> PartitionsResponse:
+        """List the partitions of ``asset``, optionally filtered by coin/month."""
+        response = await self._request(_base.partitions_request(asset, coin, month))
+        return PartitionsResponse.model_validate_json(response.content)
+
+    async def download_url(self, asset: str, coin: str, month: str) -> DownloadResponse:
+        """Mint a short-lived presigned download URL for one partition."""
+        response = await self._request(_base.download_request(asset, coin, month))
+        return DownloadResponse.model_validate_json(response.content)
+
+    # -- partition helpers -------------------------------------------------
+    def partition_refs(self, asset: str, coin: Coins, month: Months) -> list[PartitionRef]:
+        """Expand ``(asset, coins, months)`` into concrete partition references."""
+        return expand_refs(asset, coin, month)
+
+    async def _resolve(self, refs: Sequence[PartitionRef]) -> list[_resolver.ResolvedPartition]:
+        async def fetch(ref: PartitionRef) -> str:
+            return (await self.download_url(ref.asset, ref.coin, ref.month)).url
+
+        return await _resolver.resolve_async(fetch, refs)
+
+    # -- data loading ------------------------------------------------------
+    async def scan(
+        self,
+        asset: str,
+        coin: Coins,
+        month: Months,
+        *,
+        columns: Sequence[str] | None = None,
+    ) -> pl.LazyFrame:
+        """Lazily scan one or more partitions into a Polars ``LazyFrame``."""
+        _polars_reader.ensure_available()
+        parts = await self._resolve(expand_refs(asset, coin, month))
+        return _polars_reader.build_lazyframe(parts, columns=columns)
+
+    async def read(
+        self,
+        asset: str,
+        coin: Coins,
+        month: Months,
+        *,
+        columns: Sequence[str] | None = None,
+    ) -> pl.DataFrame:
+        """Eagerly read one or more partitions into a Polars ``DataFrame``."""
+        _polars_reader.ensure_available()
+        parts = await self._resolve(expand_refs(asset, coin, month))
+        lazyframe = _polars_reader.build_lazyframe(parts, columns=columns)
+        return await asyncio.to_thread(_polars_reader.collect, lazyframe)
+
+    async def to_duckdb(
+        self,
+        asset: str,
+        coin: Coins,
+        month: Months,
+        *,
+        connection: duckdb.DuckDBPyConnection | None = None,
+        columns: Sequence[str] | None = None,
+    ) -> duckdb.DuckDBPyRelation:
+        """Open one or more partitions as a DuckDB relation for SQL querying."""
+        _duckdb_reader.ensure_available()
+        parts = await self._resolve(expand_refs(asset, coin, month))
+        return await asyncio.to_thread(
+            lambda: _duckdb_reader.build_relation(parts, connection=connection, columns=columns)
+        )
+
+    async def to_pandas(
+        self,
+        asset: str,
+        coin: Coins,
+        month: Months,
+        *,
+        columns: Sequence[str] | None = None,
+    ) -> pandas.DataFrame:
+        """Convenience escape hatch: read into a pandas ``DataFrame`` (via Polars)."""
+        frame = await self.read(asset, coin, month, columns=columns)
+        return frame_to_pandas(frame)  # type: ignore[return-value]

tessera/client.py

@@ -0,0 +1,197 @@
+"""Synchronous Tessera API client."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Sequence
+from types import TracebackType
+from typing import TYPE_CHECKING
+
+import httpx
+
+from . import _base, _resolver
+from .config import DEFAULT_BASE_URL, ClientConfig, backoff_delay, resolve_api_key
+from .errors import NetworkError
+from .models import (
+    Coins,
+    DatasetsResponse,
+    DownloadResponse,
+    Months,
+    PartitionRef,
+    PartitionsResponse,
+)
+from .readers import duckdb as _duckdb_reader
+from .readers import polars as _polars_reader
+from .readers._common import expand_refs, frame_to_pandas
+
+if TYPE_CHECKING:
+    import duckdb
+    import pandas
+    import polars as pl
+
+__all__ = ["TesseraClient"]
+
+
+class TesseraClient:
+    """A synchronous client for the Tessera API.
+
+    Args:
+        api_key: Your Tessera API key. Falls back to ``$TESSERA_API_KEY``.
+        base_url: API base URL. Defaults to the production endpoint.
+        timeout: Per-request timeout in seconds.
+        max_retries: Retries for transient failures (429/5xx, network errors).
+        http_client: Inject your own ``httpx.Client`` (advanced; overrides the
+            timeout/base-url defaults — you are responsible for auth headers).
+
+    Example:
+        >>> client = TesseraClient()
+        >>> df = client.read("gold_ohlcv_1m", "BTC", "2025-09")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.config = ClientConfig(
+            api_key=resolve_api_key(api_key),
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        if http_client is not None:
+            self._http = http_client
+            self._owns_http = False
+        else:
+            self._http = httpx.Client(**_base.build_httpx_kwargs(self.config))  # type: ignore[arg-type]
+            self._owns_http = True
+
+    # -- lifecycle ---------------------------------------------------------
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> TesseraClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    # -- transport ---------------------------------------------------------
+    def _request(self, prepared: _base.PreparedRequest) -> httpx.Response:
+        for attempt in range(self.config.max_retries + 1):
+            last = attempt == self.config.max_retries
+            try:
+                response = self._http.get(prepared.path, params=prepared.params or None)
+            except httpx.TransportError as exc:
+                if last:
+                    raise NetworkError(f"network error contacting Tessera: {exc}") from exc
+                time.sleep(backoff_delay(attempt, None))
+                continue
+            if not last and _base.should_retry(response.status_code):
+                time.sleep(backoff_delay(attempt, _base.parse_retry_after(response)))
+                continue
+            _base.raise_for_status(response)
+            return response
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    # -- metadata endpoints ------------------------------------------------
+    def datasets(self) -> DatasetsResponse:
+        """List every dataset visible to your plan."""
+        response = self._request(_base.datasets_request())
+        return DatasetsResponse.model_validate_json(response.content)
+
+    def partitions(
+        self,
+        asset: str,
+        *,
+        coin: str | None = None,
+        month: str | None = None,
+    ) -> PartitionsResponse:
+        """List the partitions of ``asset``, optionally filtered by coin/month."""
+        response = self._request(_base.partitions_request(asset, coin, month))
+        return PartitionsResponse.model_validate_json(response.content)
+
+    def download_url(self, asset: str, coin: str, month: str) -> DownloadResponse:
+        """Mint a short-lived presigned download URL for one partition."""
+        response = self._request(_base.download_request(asset, coin, month))
+        return DownloadResponse.model_validate_json(response.content)
+
+    # -- partition helpers -------------------------------------------------
+    def partition_refs(self, asset: str, coin: Coins, month: Months) -> list[PartitionRef]:
+        """Expand ``(asset, coins, months)`` into concrete partition references."""
+        return expand_refs(asset, coin, month)
+
+    def _resolve(self, refs: Sequence[PartitionRef]) -> list[_resolver.ResolvedPartition]:
+        return _resolver.resolve_sync(
+            lambda ref: self.download_url(ref.asset, ref.coin, ref.month).url,
+            refs,
+        )
+
+    # -- data loading ------------------------------------------------------
+    def scan(
+        self,
+        asset: str,
+        coin: Coins,
+        month: Months,
+        *,
+        columns: Sequence[str] | None = None,
+    ) -> pl.LazyFrame:
+        """Lazily scan one or more partitions into a Polars ``LazyFrame``.
+
+        URLs are minted now but the data is read on ``.collect()``. Because
+        presigned URLs expire (~15 min), collect promptly; for long-lived graphs
+        re-run ``scan`` to refresh.
+        """
+        _polars_reader.ensure_available()
+        parts = self._resolve(expand_refs(asset, coin, month))
+        return _polars_reader.build_lazyframe(parts, columns=columns)
+
+    def read(
+        self,
+        asset: str,
+        coin: Coins,
+        month: Months,
+        *,
+        columns: Sequence[str] | None = None,
+    ) -> pl.DataFrame:
+        """Eagerly read one or more partitions into a Polars ``DataFrame``."""
+        _polars_reader.ensure_available()
+        parts = self._resolve(expand_refs(asset, coin, month))
+        return _polars_reader.collect(_polars_reader.build_lazyframe(parts, columns=columns))
+
+    def to_duckdb(
+        self,
+        asset: str,
+        coin: Coins,
+        month: Months,
+        *,
+        connection: duckdb.DuckDBPyConnection | None = None,
+        columns: Sequence[str] | None = None,
+    ) -> duckdb.DuckDBPyRelation:
+        """Open one or more partitions as a DuckDB relation for SQL querying."""
+        _duckdb_reader.ensure_available()
+        parts = self._resolve(expand_refs(asset, coin, month))
+        return _duckdb_reader.build_relation(parts, connection=connection, columns=columns)
+
+    def to_pandas(
+        self,
+        asset: str,
+        coin: Coins,
+        month: Months,
+        *,
+        columns: Sequence[str] | None = None,
+    ) -> pandas.DataFrame:
+        """Convenience escape hatch: read into a pandas ``DataFrame`` (via Polars)."""
+        frame = self.read(asset, coin, month, columns=columns)
+        return frame_to_pandas(frame)  # type: ignore[return-value]