david-data 0.1.0__py3-none-any.whl

david_data/__init__.py

@@ -0,0 +1,41 @@
+"""David Data — official Python client for the David Data financial-data API.
+
+    from david_data import DavidData
+
+    dd = DavidData(api_key="...")
+    prices = dd.prices.get("AAPL", start_date="2024-01-01")
+
+See https://api.davidhf.com/docs for the full endpoint reference.
+"""
+
+from ._pandas import to_df
+from ._version import __version__
+from .client import DavidData
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    DavidDataError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+)
+
+__all__ = [
+    "DavidData",
+    "to_df",
+    "__version__",
+    "DavidDataError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+]

david_data/_http.py

@@ -0,0 +1,172 @@
+"""Low-level transport: auth header, retries with backoff, error mapping.
+
+This module is intentionally small and dependency-light (httpx only). The public
+:class:`~david_data.client.DavidData` wraps it and exposes the resource groups.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Mapping, Optional, Union
+from urllib.parse import urljoin
+
+import httpx
+
+from ._version import __version__
+from .errors import (
+    APIConnectionError,
+    APITimeoutError,
+    DavidDataError,
+    error_for_status,
+)
+
+DEFAULT_BASE_URL = "https://api.davidhf.com"
+ENV_API_KEY = "DAVID_DATA_API_KEY"
+ENV_BASE_URL = "DAVID_DATA_BASE_URL"
+
+# Status codes worth retrying: rate limits and transient server faults.
+_RETRY_STATUS = frozenset({429, 500, 502, 503, 504})
+
+
+class Transport:
+    """Owns the httpx client, applies auth, and retries idempotent failures."""
+
+    def __init__(
+        self,
+        api_key: Optional[str],
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        api_key = api_key or os.environ.get(ENV_API_KEY)
+        if not api_key:
+            raise DavidDataError(
+                "No API key provided. Pass api_key=... or set the "
+                f"{ENV_API_KEY} environment variable. Get a key at https://davidhf.com."
+            )
+        base_url = (base_url or os.environ.get(ENV_BASE_URL) or DEFAULT_BASE_URL).rstrip("/") + "/"
+        self.api_key = api_key
+        self.base_url = base_url
+        self.max_retries = max(0, int(max_retries))
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._headers = {
+            "X-API-KEY": api_key,
+            "Accept": "application/json",
+            "User-Agent": f"david-data-python/{__version__}",
+        }
+
+    # -- lifecycle ---------------------------------------------------------
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "Transport":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # -- requests ----------------------------------------------------------
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Any = None,
+    ) -> Any:
+        url = urljoin(self.base_url, path.lstrip("/"))
+        clean_params = _clean_params(params) if params else None
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method, url, params=clean_params, json=json, headers=self._headers
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = APITimeoutError(f"Request to {url} timed out: {exc}")
+            except httpx.HTTPError as exc:
+                last_exc = APIConnectionError(f"Could not reach {url}: {exc}")
+            else:
+                if response.status_code in _RETRY_STATUS and attempt < self.max_retries:
+                    time.sleep(_retry_delay(response, attempt))
+                    continue
+                return _handle_response(response)
+
+            if attempt < self.max_retries:
+                time.sleep(_backoff(attempt))
+        assert last_exc is not None
+        raise last_exc
+
+
+def _handle_response(response: httpx.Response) -> Any:
+    request_id = response.headers.get("x-request-id")
+    if response.is_success:
+        if not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+    body = _safe_body(response)
+    raise error_for_status(
+        response.status_code,
+        body=body,
+        request_id=request_id,
+        retry_after=_parse_retry_after(response),
+    )
+
+
+def _safe_body(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return response.text
+
+
+def _retry_delay(response: httpx.Response, attempt: int) -> float:
+    retry_after = _parse_retry_after(response)
+    if retry_after is not None:
+        return retry_after
+    return _backoff(attempt)
+
+
+def _parse_retry_after(response: httpx.Response) -> Optional[float]:
+    raw = response.headers.get("retry-after")
+    if not raw:
+        return None
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return None
+
+
+def _backoff(attempt: int) -> float:
+    # Exponential backoff, capped. attempt is 0-based.
+    return min(8.0, 0.5 * (2 ** attempt))
+
+
+def _clean_params(params: Mapping[str, Any]) -> dict:
+    """Drop None values and normalise dates/bools so callers can pass natural types."""
+    out: dict[str, Any] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        out[key] = _coerce(value)
+    return out
+
+
+def _coerce(value: Any) -> Union[str, int, float, list]:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    # date / datetime -> ISO string without importing datetime eagerly.
+    if hasattr(value, "isoformat") and not isinstance(value, (str, bytes)):
+        return value.isoformat()
+    if isinstance(value, (list, tuple)):
+        return [_coerce(v) for v in value]
+    return value

david_data/_pandas.py

@@ -0,0 +1,27 @@
+"""Optional pandas helpers. pandas is only imported when these are called."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def to_df(data: Any):  # noqa: ANN401 - returns a pandas.DataFrame
+    """Convert an API result into a :class:`pandas.DataFrame`.
+
+    Accepts a list of records (the common case — prices, statements, news, …)
+    or a single dict. Requires the ``pandas`` extra: ``pip install david-data[pandas]``.
+    """
+    try:
+        import pandas as pd
+    except ImportError as exc:  # pragma: no cover - exercised via extra
+        raise ImportError(
+            "pandas is required for to_df(). Install it with: pip install david-data[pandas]"
+        ) from exc
+
+    if isinstance(data, dict):
+        # A list-bearing envelope that slipped through, else a single record.
+        list_values = [v for v in data.values() if isinstance(v, list)]
+        if len(list_values) == 1:
+            return pd.DataFrame(list_values[0])
+        return pd.DataFrame([data])
+    return pd.DataFrame(data)

david_data/_version.py

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

david_data/client.py

@@ -0,0 +1,125 @@
+"""The David Data client.
+
+    from david_data import DavidData
+
+    dd = DavidData(api_key="...")          # or set DAVID_DATA_API_KEY
+    scenario = dd.scenarios.list(limit=1)[0]["id"]
+    bars = dd.prices.get("AAPL", scenario_id=scenario)
+
+Every data call is keyed by a ``scenario_id`` (a synthetic world). Discover them
+with ``dd.scenarios.list()``. Either pass ``scenario_id=`` per call, or set a
+default once with ``DavidData(..., scenario_id="my-scenario")`` and omit it
+thereafter. Calling a data endpoint with no scenario_id (and no client default)
+raises a clear error rather than guessing.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from . import resources as _r
+from ._http import Transport
+from ._version import __version__
+
+
+class DavidData:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        scenario_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        """Create a client.
+
+        Args:
+            api_key: Your David Data API key. Falls back to the
+                ``DAVID_DATA_API_KEY`` environment variable.
+            scenario_id: Default scenario applied to every data call when you
+                don't pass one explicitly. Leave it ``None`` to require an
+                explicit ``scenario_id=`` on each call. Discover ids with
+                ``client.scenarios.list()``.
+            base_url: API root. Defaults to ``DAVID_DATA_BASE_URL`` or
+                ``https://api.davidhf.com``.
+            timeout: Per-request timeout in seconds.
+            max_retries: Retries for rate limits (429) and transient 5xx errors,
+                honouring the server's ``Retry-After`` header.
+            http_client: Bring your own configured ``httpx.Client`` (proxies,
+                custom transport, etc.). The SDK will not close a client you pass.
+        """
+        self._t = Transport(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.scenario_id = scenario_id
+
+        s = scenario_id
+        t = self._t
+        #: OHLCV prices and snapshots.
+        self.prices = _r.Prices(t, s)
+        #: Financial statements, metrics, segments, KPIs, and the screener.
+        self.financials = _r.Financials(t, s)
+        #: Company directory, facts, and identifier lookups.
+        self.company = _r.Company(t, s)
+        #: News articles.
+        self.news = _r.News(t, s)
+        #: SEC-style filings and item search.
+        self.filings = _r.Filings(t, s)
+        #: Reported earnings and the earnings calendar.
+        self.earnings = _r.Earnings(t, s)
+        #: Analyst estimates and notes.
+        self.analyst = _r.Analyst(t, s)
+        #: The per-scenario event timeline.
+        self.events = _r.Events(t, s)
+        #: Insider trades and transactions.
+        self.insiders = _r.Insiders(t, s)
+        #: 13F institutional holdings.
+        self.institutional = _r.Institutional(t, s)
+        #: Index-fund constituents.
+        self.index_funds = _r.IndexFunds(t, s)
+        #: Corporate actions (splits, dividends).
+        self.corporate_actions = _r.CorporateActions(t, s)
+        #: Macro series and central-bank rates.
+        self.macro = _r.Macro(t, s)
+        #: Discover and generate scenarios.
+        self.scenarios = _r.Scenarios(t, s)
+        #: API coverage, presets, themes, and audits.
+        self.metadata = _r.Metadata(t, s)
+
+    # -- escape hatch ------------------------------------------------------
+    def get(self, path: str, **params: Any) -> Any:
+        """Call any GET endpoint directly. ``scenario_id`` is *not* injected."""
+        return self._t.request("GET", path, params=params)
+
+    def post(self, path: str, *, json: Any = None, **params: Any) -> Any:
+        """Call any POST endpoint directly."""
+        return self._t.request("POST", path, params=params or None, json=json)
+
+    def health(self) -> dict:
+        """Liveness probe (unauthenticated on the server, but routed through here)."""
+        return self._t.request("GET", "/health")
+
+    # -- lifecycle ---------------------------------------------------------
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._t.close()
+
+    def __enter__(self) -> "DavidData":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return (
+            f"DavidData(base_url={self._t.base_url!r}, scenario_id={self.scenario_id!r}, "
+            f"version={__version__!r})"
+        )

david_data/errors.py

@@ -0,0 +1,121 @@
+"""Exception hierarchy for the David Data client.
+
+Every error raised by the SDK is a subclass of :class:`DavidDataError`, so you
+can catch all of them with a single ``except DavidDataError``. HTTP failures
+carry the parsed response body and status code when available.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class DavidDataError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class APIConnectionError(DavidDataError):
+    """The request never produced a response (DNS, TLS, timeout, connection reset)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The request exceeded the configured timeout."""
+
+
+class APIStatusError(DavidDataError):
+    """The server returned a non-2xx status code.
+
+    Attributes:
+        status_code: The HTTP status code.
+        body: The parsed JSON body, or the raw text if it was not JSON.
+        detail: The server's ``detail`` message when present (FastAPI style).
+        request_id: The value of any ``x-request-id`` response header.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        body: Any = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        self.request_id = request_id
+
+    @property
+    def detail(self) -> Optional[str]:
+        if isinstance(self.body, dict):
+            d = self.body.get("detail")
+            if isinstance(d, str):
+                return d
+        return None
+
+
+class BadRequestError(APIStatusError):
+    """400 — the request parameters were rejected by the server."""
+
+
+class AuthenticationError(APIStatusError):
+    """401 — missing or invalid API key."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """403 — the key is valid but not allowed (e.g. plan quota, admin-only route)."""
+
+
+class NotFoundError(APIStatusError):
+    """404 — the scenario, ticker, or resource does not exist."""
+
+
+class RateLimitError(APIStatusError):
+    """429 — the per-minute rate limit was exceeded.
+
+    ``retry_after`` is the server-advised wait in seconds, when provided.
+    """
+
+    def __init__(self, *args: Any, retry_after: Optional[float] = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(APIStatusError):
+    """5xx — the server failed to handle a valid request."""
+
+
+_STATUS_TO_ERROR = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    429: RateLimitError,
+}
+
+
+def error_for_status(
+    status_code: int, *, body: Any, request_id: Optional[str], retry_after: Optional[float] = None
+) -> APIStatusError:
+    """Build the most specific :class:`APIStatusError` subclass for a status code."""
+    message = _message_from_body(body) or f"HTTP {status_code}"
+    if status_code == 429:
+        return RateLimitError(
+            message, status_code=status_code, body=body, request_id=request_id, retry_after=retry_after
+        )
+    cls = _STATUS_TO_ERROR.get(status_code)
+    if cls is None:
+        cls = ServerError if status_code >= 500 else APIStatusError
+    return cls(message, status_code=status_code, body=body, request_id=request_id)
+
+
+def _message_from_body(body: Any) -> Optional[str]:
+    if isinstance(body, dict):
+        detail = body.get("detail")
+        if isinstance(detail, str):
+            return detail
+        if detail is not None:
+            return str(detail)
+    if isinstance(body, str) and body.strip():
+        return body.strip()[:500]
+    return None

david_data/resources/__init__.py

@@ -0,0 +1,27 @@
+from .company import Company
+from .documents import Filings, News
+from .estimates import Analyst, Earnings, Events
+from .financials import Financials
+from .macro import Macro
+from .metadata import Metadata
+from .ownership import CorporateActions, IndexFunds, Insiders, Institutional
+from .prices import Prices
+from .scenarios import Scenarios
+
+__all__ = [
+    "Analyst",
+    "Company",
+    "CorporateActions",
+    "Earnings",
+    "Events",
+    "Filings",
+    "Financials",
+    "IndexFunds",
+    "Insiders",
+    "Institutional",
+    "Macro",
+    "Metadata",
+    "News",
+    "Prices",
+    "Scenarios",
+]

david_data/resources/base.py

@@ -0,0 +1,62 @@
+"""Shared base for resource groups.
+
+A resource group is a thin namespace (``client.prices``, ``client.financials``,
+…) whose methods translate friendly arguments into a single HTTP call and
+return the useful part of the JSON envelope.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from .._http import Transport
+from ..errors import DavidDataError
+
+
+class Resource:
+    def __init__(self, transport: Transport, default_scenario_id: Optional[str]) -> None:
+        self._t = transport
+        self._default_scenario_id = default_scenario_id
+
+    def _scenario(self, scenario_id: Optional[str]) -> str:
+        sid = scenario_id or self._default_scenario_id
+        if not sid:
+            raise DavidDataError(
+                "This endpoint requires a scenario_id. Pass scenario_id=... to the call, "
+                "or set a default on the client: DavidData(scenario_id='...'). "
+                "Browse available scenarios with client.scenarios.list()."
+            )
+        return sid
+
+    def _get(
+        self,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        unwrap: Optional[str] = None,
+    ) -> Any:
+        data = self._t.request("GET", path, params=params)
+        return _unwrap(data, unwrap)
+
+    def _post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Mapping[str, Any]] = None,
+        unwrap: Optional[str] = None,
+    ) -> Any:
+        data = self._t.request("POST", path, params=params, json=json)
+        return _unwrap(data, unwrap)
+
+
+def _unwrap(data: Any, key: Optional[str]) -> Any:
+    """Return ``data[key]`` when present, else the whole payload.
+
+    The API wraps list/object results in a single-key envelope (e.g.
+    ``{"prices": [...]}``). We return the inner value so callers get the data
+    directly, FMP-style, while still tolerating a missing/renamed key.
+    """
+    if key and isinstance(data, dict) and key in data:
+        return data[key]
+    return data

david_data/resources/company.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .base import Resource
+
+
+class Company(Resource):
+    """Company reference data: directory, facts, and identifier lookups."""
+
+    def list(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        ticker: Optional[str] = None,
+        search: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> Any:
+        """Browse or search the company directory."""
+        return self._get(
+            "/companies",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "search": search,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="companies",
+        )
+
+    def facts(
+        self,
+        ticker: Optional[str] = None,
+        *,
+        cik: Optional[str] = None,
+        scenario_id: Optional[str] = None,
+    ) -> Any:
+        """Company facts for a single ``ticker`` or ``cik``."""
+        return self._get(
+            "/company/facts",
+            params={"scenario_id": self._scenario(scenario_id), "ticker": ticker, "cik": cik},
+            unwrap="company_facts",
+        )
+
+    def tickers(self, *, scenario_id: Optional[str] = None) -> List[str]:
+        return self._get(
+            "/company/facts/tickers",
+            params={"scenario_id": self._scenario(scenario_id)},
+            unwrap="tickers",
+        )
+
+    def ciks(self, *, scenario_id: Optional[str] = None) -> Any:
+        return self._get(
+            "/company/facts/ciks",
+            params={"scenario_id": self._scenario(scenario_id)},
+            unwrap="ciks",
+        )