vanda-api 0.1.0__py3-none-any.whl

vanda/__init__.py

@@ -0,0 +1,25 @@
+from vanda.async_client import AsyncVandaClient
+from vanda.client import VandaClient
+from vanda.errors import (
+    AuthError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+    ValidationError,
+    VandaError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "VandaClient",
+    "AsyncVandaClient",
+    "VandaError",
+    "AuthError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "ServerError",
+    "TransportError",
+]

vanda/async_client.py

@@ -0,0 +1,614 @@
+import asyncio
+import logging
+import time
+from datetime import date, datetime
+from typing import Any, Optional, Union
+
+import httpx
+
+from vanda.auth import Auth
+from vanda.errors import (
+    AuthError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+    ValidationError,
+    VandaError,
+)
+from vanda.models import CompressionType, ExportFormat, StreamFormat
+from vanda.utils.dates import format_date, validate_date_range
+from vanda.utils.io import write_stream_to_file
+from vanda.utils.normalize import normalize_result
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncVandaClient:
+    """
+    Asynchronous client for Vanda Analytics API.
+
+    Example:
+        async with AsyncVandaClient(token="YOUR_TOKEN_HERE") as client:
+            data = await client.get_timeseries("TSLA", "2025-12-01", "2025-12-31", ["retail_net_turnover"])
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        base_url: str = "https://stg.api.vanda-analytics.com",
+        timeout: float = 600.0,
+        max_retries: int = 3,
+    ) -> None:
+        """
+        Initialize async Vanda client.
+
+        Args:
+            token: API token. If None, reads from VANDA_API_TOKEN environment variable.
+            base_url: API base URL.
+            timeout: Request timeout in seconds.
+            max_retries: Maximum retry attempts.
+
+        Raises:
+            AuthError: If token is not provided.
+        """
+        self.auth = Auth(token)
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._client: Optional[httpx.AsyncClient] = None
+
+    async def __aenter__(self) -> "AsyncVandaClient":
+        """Async context manager entry."""
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=self.auth.get_headers(),
+            timeout=self.timeout,
+        )
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        """Async context manager exit."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    @property
+    def client(self) -> httpx.AsyncClient:
+        """Get HTTP client, creating if necessary."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=self.auth.get_headers(),
+                timeout=self.timeout,
+            )
+        return self._client
+
+    async def close(self) -> None:
+        """Close HTTP client."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    def _handle_error(self, response: httpx.Response) -> None:
+        """Handle HTTP error responses."""
+        status_code = response.status_code
+        request_id = response.headers.get("x-request-id")
+
+        try:
+            body = response.json()
+            detail = body.get("detail", response.text)
+        except Exception:
+            detail = response.text
+            body = None
+
+        if status_code == 401 or status_code == 403:
+            raise AuthError(
+                f"Authentication failed: {detail}",
+                status_code=status_code,
+                request_id=request_id,
+                response_body=body,
+            )
+        elif status_code == 404:
+            raise NotFoundError(
+                f"Resource not found: {detail}",
+                status_code=status_code,
+                request_id=request_id,
+                response_body=body,
+            )
+        elif status_code == 422:
+            raise ValidationError(
+                f"Validation error: {detail}",
+                status_code=status_code,
+                request_id=request_id,
+                response_body=body,
+            )
+        elif status_code == 429:
+            retry_after = response.headers.get("retry-after")
+            retry_after_int = int(retry_after) if retry_after else None
+            raise RateLimitError(
+                f"Rate limit exceeded: {detail}",
+                retry_after=retry_after_int,
+                status_code=status_code,
+                request_id=request_id,
+                response_body=body,
+            )
+        elif status_code >= 500:
+            raise ServerError(
+                f"Server error: {detail}",
+                status_code=status_code,
+                request_id=request_id,
+                response_body=body,
+            )
+        else:
+            raise VandaError(
+                f"HTTP {status_code}: {detail}",
+                status_code=status_code,
+                request_id=request_id,
+                response_body=body,
+            )
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+        json: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """Make async HTTP request with retry logic."""
+        start_time = time.time()
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                logger.debug(
+                    "http_request method=%s path=%s attempt=%d headers=%s",
+                    method,
+                    path,
+                    attempt,
+                    self.auth.get_headers_safe(),
+                )
+                response = await self.client.request(method, path, params=params, json=json)
+                response.raise_for_status()
+                latency = time.time() - start_time
+                logger.info(
+                    "http_success method=%s path=%s status=%d latency=%.3f attempts=%d",
+                    method,
+                    path,
+                    response.status_code,
+                    latency,
+                    attempt + 1,
+                )
+                return response.json()
+            except httpx.HTTPStatusError as e:
+                if (
+                    e.response.status_code not in {429, 500, 502, 503, 504}
+                    or attempt == self.max_retries
+                ):
+                    latency = time.time() - start_time
+                    logger.error(
+                        "http_error method=%s path=%s status=%d latency=%.3f",
+                        method,
+                        path,
+                        e.response.status_code,
+                        latency,
+                    )
+                    self._handle_error(e.response)
+                delay = min(1.0 * (2**attempt), 32.0)
+                logger.warning(
+                    "http_retry method=%s path=%s status=%d retry=%d delay=%.2f",
+                    method,
+                    path,
+                    e.response.status_code,
+                    attempt + 1,
+                    delay,
+                )
+                await asyncio.sleep(delay)
+            except (httpx.TimeoutException, httpx.NetworkError) as e:
+                if attempt == self.max_retries:
+                    raise TransportError(f"Network error: {e}") from e
+                delay = min(1.0 * (2**attempt), 32.0)
+                logger.warning(
+                    "network_retry method=%s path=%s retry=%d delay=%.2f",
+                    method,
+                    path,
+                    attempt + 1,
+                    delay,
+                )
+                await asyncio.sleep(delay)
+
+        raise RuntimeError("Retry logic failed unexpectedly")
+
+    async def _request_stream(
+        self,
+        method: str,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+    ) -> bytes:
+        """Make async streaming HTTP request."""
+        start_time = time.time()
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self.client.request(method, path, params=params)
+                response.raise_for_status()
+                latency = time.time() - start_time
+                logger.info(
+                    "http_stream_success method=%s path=%s status=%d latency=%.3f size_kb=%.2f",
+                    method,
+                    path,
+                    response.status_code,
+                    latency,
+                    len(response.content) / 1024,
+                )
+                return response.content
+            except httpx.HTTPStatusError as e:
+                if (
+                    e.response.status_code not in {429, 500, 502, 503, 504}
+                    or attempt == self.max_retries
+                ):
+                    latency = time.time() - start_time
+                    logger.error(
+                        "http_error method=%s path=%s status=%d latency=%.3f",
+                        method,
+                        path,
+                        e.response.status_code,
+                        latency,
+                    )
+                    self._handle_error(e.response)
+                delay = min(1.0 * (2**attempt), 32.0)
+                await asyncio.sleep(delay)
+            except (httpx.TimeoutException, httpx.NetworkError) as e:
+                if attempt == self.max_retries:
+                    raise TransportError(f"Network error: {e}") from e
+                delay = min(1.0 * (2**attempt), 32.0)
+                await asyncio.sleep(delay)
+
+        raise RuntimeError("Retry logic failed unexpectedly")
+
+    async def get_timeseries(
+        self,
+        symbol: str,
+        start_date: Union[str, date, datetime],
+        end_date: Union[str, date, datetime],
+        fields: list[str],
+        interval: str = "1d",
+        asset_class: str = "cash",
+        records_per_page: int = 2000,
+        page_number: int = 1,
+        order: str = "asc",
+        calculate_metrics: bool = False,
+        options_type: str = "ALL",
+        options_notional: str = "ALL",
+        options_moneyness: str = "TOTAL",
+        options_size: str = "TOTAL",
+    ) -> list[dict[str, Any]]:
+        """Get timeseries data for a symbol."""
+        start_str = format_date(start_date)
+        end_str = format_date(end_date)
+        validate_date_range(start_str, end_str)
+
+        params: dict[str, Any] = {
+            "symbol": symbol,
+            "interval": interval,
+            "start_date": start_str,
+            "end_date": end_str,
+            "fields": fields,
+            "asset_class": asset_class,
+            "records_per_page": records_per_page,
+            "page_number": page_number,
+            "order": order,
+            "calculate_metrics": str(calculate_metrics).lower(),
+        }
+
+        if asset_class == "options":
+            params.update(
+                {
+                    "type": options_type,
+                    "notional": options_notional,
+                    "moneyness": options_moneyness,
+                    "size": options_size,
+                }
+            )
+
+        data = await self._request("GET", "/series/timeseries", params=params)
+
+        if "job_id" in data:
+            result = await self.poll_job(data["job_id"])
+            return normalize_result(result)
+
+        return normalize_result(data)
+
+    async def get_timeseries_many(
+        self,
+        symbols: list[str],
+        start_date: Union[str, date, datetime],
+        end_date: Union[str, date, datetime],
+        fields: list[str],
+        **kwargs: Any,
+    ) -> list[dict[str, Any]]:
+        """Get timeseries data for multiple symbols concurrently."""
+        tasks = [
+            self.get_timeseries(symbol, start_date, end_date, fields, **kwargs)
+            for symbol in symbols
+        ]
+        results = await asyncio.gather(*tasks)
+        all_records = []
+        for records in results:
+            all_records.extend(records)
+        return all_records
+
+    async def get_leaderboard(
+        self,
+        interval: str = "1d",
+        metric: str = "retail_net_turnover",
+        records_per_page: int = 2000,
+        page_number: int = 1,
+        asset_class: str = "cash",
+        start_date: Optional[Union[str, date, datetime]] = None,
+        end_date: Optional[Union[str, date, datetime]] = None,
+        date_filter: Optional[Union[str, date, datetime]] = None,
+        sector: Optional[str] = None,
+        options_type: str = "ALL",
+        options_notional: str = "ALL",
+        options_moneyness: str = "TOTAL",
+        options_size: str = "TOTAL",
+    ) -> list[dict[str, Any]]:
+        """Get leaderboard data."""
+        params: dict[str, Any] = {
+            "interval": interval,
+            "metric": metric,
+            "records_per_page": records_per_page,
+            "page_number": page_number,
+            "asset_class": asset_class,
+        }
+
+        if start_date:
+            params["start_date"] = format_date(start_date)
+        if end_date:
+            params["end_date"] = format_date(end_date)
+        if date_filter:
+            params["date"] = format_date(date_filter)
+        if sector:
+            params["sector"] = sector
+
+        if asset_class == "options":
+            params.update(
+                {
+                    "type": options_type,
+                    "notional": options_notional,
+                    "moneyness": options_moneyness,
+                    "size": options_size,
+                }
+            )
+
+        data = await self._request("GET", "/series/timeseries/leaderboard", params=params)
+        return normalize_result(data)
+
+    async def create_bulk_securities_job(
+        self,
+        interval: str = "1d",
+        asset_class: str = "cash",
+        start_date: Optional[Union[str, date, datetime]] = None,
+        end_date: Optional[Union[str, date, datetime]] = None,
+        fields: Optional[list[str]] = None,
+        identifiers: Optional[list[str]] = None,
+        all: bool = False,
+        options_type: str = "ALL",
+        options_notional: str = "ALL",
+        options_moneyness: str = "TOTAL",
+        options_size: str = "TOTAL",
+    ) -> str:
+        """Create bulk securities job."""
+        if not all and not identifiers:
+            raise ValidationError("Must provide identifiers or set all=True")
+
+        payload: dict[str, Any] = {
+            "interval": interval,
+            "asset_class": asset_class,
+        }
+
+        if all:
+            payload["all"] = True
+        elif identifiers:
+            payload["identifiers"] = identifiers
+
+        if start_date:
+            payload["start_date"] = format_date(start_date)
+        if end_date:
+            payload["end_date"] = format_date(end_date)
+        if fields:
+            payload["fields"] = fields
+
+        if asset_class == "options":
+            payload.update(
+                {
+                    "type": options_type,
+                    "notional": options_notional,
+                    "moneyness": options_moneyness,
+                    "size": options_size,
+                }
+            )
+
+        data = await self._request("POST", "/series/bulk/securities", json=payload)
+        return data["job_id"]
+
+    async def bulk_securities(
+        self,
+        wait: bool = True,
+        poll_interval: int = 5,
+        max_wait: int = 600,
+        **kwargs: Any,
+    ) -> Union[str, list[dict[str, Any]]]:
+        """Fetch bulk securities data."""
+        job_id = await self.create_bulk_securities_job(**kwargs)
+        if not wait:
+            return job_id
+        result = await self.poll_job(job_id, poll_interval=poll_interval, max_wait=max_wait)
+        return normalize_result(result)
+
+    async def get_daily_snapshot(
+        self,
+        interval: str = "1d",
+        asset_class: str = "cash",
+        limit: int = 2000,
+        date_filter: Optional[Union[str, date, datetime]] = None,
+        fields: Optional[list[str]] = None,
+        is_active: Optional[bool] = None,
+        sector: Optional[str] = None,
+        wait: bool = True,
+        poll_interval: int = 5,
+        max_wait: int = 600,
+        options_type: str = "ALL",
+        options_notional: str = "ALL",
+        options_moneyness: str = "TOTAL",
+        options_size: str = "TOTAL",
+    ) -> Union[str, list[dict[str, Any]]]:
+        """Get daily snapshot for many securities."""
+        payload: dict[str, Any] = {
+            "interval": interval,
+            "asset_class": asset_class,
+            "limit": limit,
+        }
+
+        if date_filter:
+            payload["date"] = format_date(date_filter)
+        if fields:
+            payload["fields"] = fields
+        if is_active is not None:
+            payload["is_active"] = is_active
+        if sector:
+            payload["sector"] = sector
+
+        if asset_class == "options":
+            payload.update(
+                {
+                    "type": options_type,
+                    "notional": options_notional,
+                    "moneyness": options_moneyness,
+                    "size": options_size,
+                }
+            )
+
+        data = await self._request("POST", "/series/bulk/daily/snapshot", json=payload)
+
+        if "job_id" in data:
+            job_id = data["job_id"]
+            if not wait:
+                return job_id
+            result = await self.poll_job(job_id, poll_interval=poll_interval, max_wait=max_wait)
+            return normalize_result(result)
+
+        return normalize_result(data)
+
+    async def get_job(self, job_id: str) -> dict[str, Any]:
+        """Get job status and result."""
+        return await self._request("GET", f"/series/jobs/{job_id}")
+
+    async def get_job_status(self, job_id: str) -> dict[str, Any]:
+        """Get job status only."""
+        return await self._request("GET", f"/series/jobs/{job_id}/status")
+
+    async def poll_job(
+        self, job_id: str, poll_interval: int = 5, max_wait: int = 600
+    ) -> dict[str, Any]:
+        """Poll job until completion."""
+        start_time = time.time()
+        while time.time() - start_time < max_wait:
+            status_data = await self.get_job(job_id)
+            status = status_data.get("status", "").upper()
+
+            logger.debug("job_poll job_id=%s status=%s", job_id, status)
+
+            if status == "COMPLETED":
+                logger.info("job_completed job_id=%s", job_id)
+                return status_data.get("result", {})
+            elif status == "FAILED":
+                error = status_data.get("error", "Unknown error")
+                logger.error("job_failed job_id=%s error=%s", job_id, error)
+                raise VandaError(f"Job failed: {error}")
+
+            await asyncio.sleep(poll_interval)
+
+        raise VandaError(f"Job polling timeout after {max_wait}s")
+
+    async def wait_for_job(self, job_id: str, **kwargs: Any) -> dict[str, Any]:
+        """Alias for poll_job."""
+        return await self.poll_job(job_id, **kwargs)
+
+    async def export_job_result(
+        self,
+        job_id: str,
+        export_format: ExportFormat = "csv",
+        compression: CompressionType = "none",
+        output_path: str = "",
+    ) -> None:
+        """Export job result to file."""
+        params = {"export_format": export_format, "compression": compression}
+        content = await self._request_stream("GET", f"/series/jobs/{job_id}/export", params=params)
+        write_stream_to_file(content, output_path)
+
+    async def stream_job_result(
+        self, job_id: str, format: StreamFormat = "ndjson", output_path: str = ""
+    ) -> None:
+        """Stream job result to file."""
+        params = {"format": format}
+        content = await self._request_stream("GET", f"/series/jobs/{job_id}/stream", params=params)
+        write_stream_to_file(content, output_path)
+
+    async def export_timeseries(
+        self,
+        symbol: Optional[str] = None,
+        vanda_id: Optional[str] = None,
+        interval: str = "1d",
+        start_date: Optional[Union[str, date, datetime]] = None,
+        end_date: Optional[Union[str, date, datetime]] = None,
+        export_format: ExportFormat = "csv",
+        compression: CompressionType = "none",
+        asset_class: str = "cash",
+        output_path: str = "",
+    ) -> None:
+        """Export timeseries data to file."""
+        if not symbol and not vanda_id:
+            raise ValidationError("Must provide either symbol or vanda_id")
+        if symbol and vanda_id:
+            raise ValidationError("Cannot provide both symbol and vanda_id")
+
+        params: dict[str, Any] = {
+            "interval": interval,
+            "export_format": export_format,
+            "compression": compression,
+            "asset_class": asset_class,
+        }
+
+        if symbol:
+            params["symbol"] = symbol
+        if vanda_id:
+            params["vanda_id"] = vanda_id
+        if start_date:
+            params["start_date"] = format_date(start_date)
+        if end_date:
+            params["end_date"] = format_date(end_date)
+
+        content = await self._request_stream("GET", "/series/timeseries/export", params=params)
+        write_stream_to_file(content, output_path)
+
+    async def list_fields(self, asset_class: str = "cash") -> dict[str, Any]:
+        """List available fields for asset class."""
+        params = {"asset_class": asset_class}
+        return await self._request("GET", "/series/timeseries/fields", params=params)
+
+    async def list_intervals(self) -> dict[str, Any]:
+        """List available time intervals."""
+        return await self._request("GET", "/series/timeseries/intervals")
+
+    async def list_securities(
+        self, asset_class: str = "cash", limit: int = 2000, is_active: bool = True
+    ) -> list[dict[str, Any]]:
+        """List available securities."""
+        params = {
+            "asset_class": asset_class,
+            "limit": limit,
+            "is_active": str(is_active).lower(),
+        }
+        data = await self._request("GET", "/series/timeseries/list", params=params)
+        return normalize_result(data)

vanda/auth.py

@@ -0,0 +1,33 @@
+import os
+from typing import Optional
+
+from vanda.errors import AuthError
+
+
+class Auth:
+    """Manages authentication tokens."""
+
+    def __init__(self, token: Optional[str] = None, env_var: str = "VANDA_API_TOKEN") -> None:
+        """
+        Initialize authentication.
+
+        Args:
+            token: API token. If None, reads from environment variable.
+            env_var: Environment variable name to read token from.
+
+        Raises:
+            AuthError: If token is not provided and not found in environment.
+        """
+        self._token = token or os.getenv(env_var)
+        if not self._token:
+            raise AuthError(
+                f"API token not provided. Pass token= or set {env_var} environment variable."
+            )
+
+    def get_headers(self) -> dict[str, str]:
+        """Return authentication headers."""
+        return {"Authorization": f"Bearer {self._token}"}
+
+    def get_headers_safe(self) -> dict[str, str]:
+        """Return headers with token redacted (for logging)."""
+        return {"Authorization": "Bearer ***"}