david-data 0.1.0__py3-none-any.whl

david_data/resources/documents.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .base import Resource
+
+DateLike = Any
+
+
+class News(Resource):
+    """Synthetic / real news articles."""
+
+    def list(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        ticker: Optional[str] = None,
+        as_of: Optional[DateLike] = None,
+        start_date: Optional[DateLike] = None,
+        end_date: Optional[DateLike] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/news",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "as_of": as_of,
+                "start_date": start_date,
+                "end_date": end_date,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="news",
+        )
+
+    def get(self, artifact_id: str, *, scenario_id: Optional[str] = None) -> dict:
+        """Fetch the full body of a single news article."""
+        return self._get(
+            f"/news/{artifact_id}",
+            params={"scenario_id": self._scenario(scenario_id)},
+            unwrap="news_article",
+        )
+
+
+class Filings(Resource):
+    """SEC-style filings: index, full-text item search, and facet lookups."""
+
+    def list(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        ticker: Optional[str] = None,
+        filing_type: Optional[str] = None,
+        start_date: Optional[DateLike] = None,
+        end_date: Optional[DateLike] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/filings",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "filing_type": filing_type,
+                "start_date": start_date,
+                "end_date": end_date,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="filings",
+        )
+
+    def items(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        ticker: Optional[str] = None,
+        filing_type: Optional[str] = None,
+        item: Optional[str] = None,
+        year: Optional[int] = None,
+        quarter: Optional[int] = None,
+        start_date: Optional[DateLike] = None,
+        end_date: Optional[DateLike] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[dict]:
+        """Filing items with their extracted text (e.g. 10-K Item 1A, 8-K items)."""
+        return self._get(
+            "/filings/items",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "filing_type": filing_type,
+                "item": item,
+                "year": year,
+                "quarter": quarter,
+                "start_date": start_date,
+                "end_date": end_date,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="filing_items",
+        )
+
+    def types(self, *, scenario_id: Optional[str] = None) -> Any:
+        return self._get(
+            "/filings/types",
+            params={"scenario_id": self._scenario(scenario_id)},
+            unwrap="filing_types",
+        )
+
+    def item_types(self, *, scenario_id: Optional[str] = None) -> Any:
+        return self._get(
+            "/filings/items/types",
+            params={"scenario_id": self._scenario(scenario_id)},
+            unwrap="item_types",
+        )
+
+    def tickers(self, *, scenario_id: Optional[str] = None) -> List[str]:
+        return self._get(
+            "/filings/tickers", params={"scenario_id": self._scenario(scenario_id)}, unwrap="tickers"
+        )
+
+    def ciks(self, *, scenario_id: Optional[str] = None) -> Any:
+        return self._get(
+            "/filings/ciks", params={"scenario_id": self._scenario(scenario_id)}, unwrap="ciks"
+        )

david_data/resources/estimates.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .base import Resource
+
+DateLike = Any
+
+
+class Earnings(Resource):
+    """Reported earnings and the forward earnings calendar."""
+
+    def list(
+        self,
+        ticker: Optional[str] = None,
+        *,
+        scenario_id: Optional[str] = None,
+        limit: int = 8,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/earnings",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="earnings",
+        )
+
+    def calendar(
+        self, ticker: str, *, scenario_id: Optional[str] = None, limit: int = 8, offset: int = 0
+    ) -> List[dict]:
+        return self._get(
+            "/earnings/calendar",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="earnings",
+        )
+
+    def tickers(self, *, scenario_id: Optional[str] = None) -> List[str]:
+        return self._get(
+            "/earnings/tickers",
+            params={"scenario_id": self._scenario(scenario_id)},
+            unwrap="tickers",
+        )
+
+
+class Analyst(Resource):
+    """Sell-side analyst estimates and analyst notes."""
+
+    def estimates(
+        self,
+        ticker: str,
+        *,
+        scenario_id: Optional[str] = None,
+        as_of: Optional[DateLike] = None,
+        limit: int = 8,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/analyst-estimates",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "as_of": as_of,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="analyst_estimates",
+        )
+
+    def notes(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        ticker: Optional[str] = None,
+        as_of: Optional[DateLike] = None,
+        start_date: Optional[DateLike] = None,
+        end_date: Optional[DateLike] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/analyst-notes",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "as_of": as_of,
+                "start_date": start_date,
+                "end_date": end_date,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="analyst_notes",
+        )
+
+
+class Events(Resource):
+    """The per-scenario event timeline (catalysts, regime shifts, corporate events)."""
+
+    def timeline(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        ticker: Optional[str] = None,
+        as_of: Optional[DateLike] = None,
+        event_type: Optional[str] = None,
+        start_date: Optional[DateLike] = None,
+        end_date: Optional[DateLike] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/events/timeline",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "as_of": as_of,
+                "event_type": event_type,
+                "start_date": start_date,
+                "end_date": end_date,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="events",
+        )

david_data/resources/financials.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .base import Resource
+
+DateLike = Any
+
+
+class Financials(Resource):
+    """Financial statements, derived metrics, segments, KPIs, and the screener.
+
+    ``period`` is one of ``"annual"``, ``"quarterly"`` or ``"ttm"`` where the
+    endpoint supports it.
+    """
+
+    # -- income statements ------------------------------------------------
+    def income_statements(
+        self,
+        ticker: str,
+        *,
+        scenario_id: Optional[str] = None,
+        period: str = "annual",
+        report_period_gte: Optional[DateLike] = None,
+        report_period_lte: Optional[DateLike] = None,
+        limit: int = 4,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/financials/income-statements",
+            params=self._period_params(
+                ticker, scenario_id, period, limit, offset, report_period_gte, report_period_lte
+            ),
+            unwrap="income_statements",
+        )
+
+    def balance_sheets(
+        self,
+        ticker: str,
+        *,
+        scenario_id: Optional[str] = None,
+        period: str = "annual",
+        report_period_gte: Optional[DateLike] = None,
+        report_period_lte: Optional[DateLike] = None,
+        limit: int = 4,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/financials/balance-sheets",
+            params=self._period_params(
+                ticker, scenario_id, period, limit, offset, report_period_gte, report_period_lte
+            ),
+            unwrap="balance_sheets",
+        )
+
+    def cash_flow_statements(
+        self,
+        ticker: str,
+        *,
+        scenario_id: Optional[str] = None,
+        period: str = "annual",
+        report_period_gte: Optional[DateLike] = None,
+        report_period_lte: Optional[DateLike] = None,
+        limit: int = 4,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/financials/cash-flow-statements",
+            params=self._period_params(
+                ticker, scenario_id, period, limit, offset, report_period_gte, report_period_lte
+            ),
+            unwrap="cash_flow_statements",
+        )
+
+    def all_statements(
+        self,
+        ticker: str,
+        *,
+        scenario_id: Optional[str] = None,
+        period: str = "annual",
+        report_period_gte: Optional[DateLike] = None,
+        report_period_lte: Optional[DateLike] = None,
+        limit: int = 4,
+        offset: int = 0,
+    ) -> dict:
+        """All three statements together (the ``/financials`` combined endpoint)."""
+        return self._get(
+            "/financials",
+            params=self._period_params(
+                ticker, scenario_id, period, limit, offset, report_period_gte, report_period_lte
+            ),
+            unwrap="financials",
+        )
+
+    # -- as-reported & segments ------------------------------------------
+    def as_reported(
+        self,
+        ticker: str,
+        *,
+        statement: Optional[str] = None,
+        scenario_id: Optional[str] = None,
+        period: str = "annual",
+        limit: int = 4,
+        offset: int = 0,
+    ) -> Any:
+        """As-reported line items.
+
+        ``statement`` selects one of ``"income"``, ``"balance"``, ``"cash-flow"``;
+        omit it for the combined ``/financials/as-reported`` view.
+        """
+        path = {
+            None: "/financials/as-reported",
+            "income": "/financials/income-statements/as-reported",
+            "balance": "/financials/balance-sheets/as-reported",
+            "cash-flow": "/financials/cash-flow-statements/as-reported",
+        }[statement]
+        return self._get(
+            path, params=self._period_params(ticker, scenario_id, period, limit, offset)
+        )
+
+    def segments(
+        self,
+        ticker: str,
+        *,
+        statement: Optional[str] = None,
+        scenario_id: Optional[str] = None,
+        period: str = "annual",
+        limit: int = 4,
+        offset: int = 0,
+    ) -> Any:
+        """Segmented financials. ``statement`` as in :meth:`as_reported`."""
+        path = {
+            None: "/financials/segments",
+            "income": "/financials/income-statements/segments",
+            "balance": "/financials/balance-sheets/segments",
+            "cash-flow": "/financials/cash-flow-statements/segments",
+        }[statement]
+        return self._get(
+            path, params=self._period_params(ticker, scenario_id, period, limit, offset)
+        )
+
+    # -- metrics ----------------------------------------------------------
+    def metrics(
+        self,
+        ticker: str,
+        *,
+        scenario_id: Optional[str] = None,
+        period: str = "ttm",
+        limit: int = 4,
+        offset: int = 0,
+    ) -> List[dict]:
+        """Derived ratios and per-share metrics over time."""
+        return self._get(
+            "/financial-metrics",
+            params=self._period_params(ticker, scenario_id, period, limit, offset),
+            unwrap="financial_metrics",
+        )
+
+    def metrics_snapshot(
+        self,
+        ticker: Optional[str] = None,
+        *,
+        scenario_id: Optional[str] = None,
+        as_of: Optional[DateLike] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> Any:
+        """Latest metric values; omit ``ticker`` for a market-wide snapshot."""
+        return self._get(
+            "/financial-metrics/snapshot",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "as_of": as_of,
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+
+    # -- KPIs -------------------------------------------------------------
+    def kpi_metrics(self, ticker: str, *, scenario_id: Optional[str] = None, period: str = "quarterly", limit: int = 8, offset: int = 0) -> Any:
+        return self._get(
+            "/kpi/metrics",
+            params=self._period_params(ticker, scenario_id, period, limit, offset),
+            unwrap="kpi_metrics",
+        )
+
+    def kpi_guidance(self, ticker: str, *, scenario_id: Optional[str] = None, period: str = "quarterly", limit: int = 8, offset: int = 0) -> Any:
+        return self._get(
+            "/kpi/guidance",
+            params=self._period_params(ticker, scenario_id, period, limit, offset),
+            unwrap="kpi_guidance",
+        )
+
+    def kpi_non_gaap(self, ticker: str, *, scenario_id: Optional[str] = None, period: str = "quarterly", limit: int = 8, offset: int = 0) -> Any:
+        return self._get(
+            "/kpi/non-gaap",
+            params=self._period_params(ticker, scenario_id, period, limit, offset),
+            unwrap="non_gaap",
+        )
+
+    # -- screener / line-item search -------------------------------------
+    def screener(self, filters: List[dict], *, scenario_id: Optional[str] = None, **body: Any) -> Any:
+        """Run the fundamentals screener.
+
+        ``filters`` is a list of ``{"field": ..., "operator": ..., "value": ...}``
+        clauses. See :meth:`screener_filters` for the supported fields.
+        """
+        payload = {"scenario_id": self._scenario(scenario_id), "filters": filters, **body}
+        return self._post("/financials/search/screener", json=payload, unwrap="results")
+
+    def line_items(self, line_items: List[str], tickers: List[str], *, scenario_id: Optional[str] = None, **body: Any) -> Any:
+        """Fetch specific named line items across one or more tickers."""
+        payload = {
+            "scenario_id": self._scenario(scenario_id),
+            "line_items": line_items,
+            "tickers": tickers,
+            **body,
+        }
+        return self._post("/financials/search/line-items", json=payload, unwrap="results")
+
+    def screener_filters(self) -> Any:
+        """List the fields the screener accepts."""
+        return self._get("/financials/search/screener/filters")
+
+    # -- helpers ----------------------------------------------------------
+    def _period_params(
+        self,
+        ticker: str,
+        scenario_id: Optional[str],
+        period: str,
+        limit: int,
+        offset: int,
+        report_period_gte: Optional[DateLike] = None,
+        report_period_lte: Optional[DateLike] = None,
+    ) -> dict:
+        params = {
+            "scenario_id": self._scenario(scenario_id),
+            "ticker": ticker,
+            "period": period,
+            "limit": limit,
+            "offset": offset,
+        }
+        if report_period_gte is not None:
+            params["report_period_gte"] = report_period_gte
+        if report_period_lte is not None:
+            params["report_period_lte"] = report_period_lte
+        return params

david_data/resources/macro.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .base import Resource
+
+DateLike = Any
+
+
+class Macro(Resource):
+    """Macro series and central-bank interest rates."""
+
+    def series(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        start_date: Optional[DateLike] = None,
+        end_date: Optional[DateLike] = None,
+        limit: int = 1000,
+        offset: int = 0,
+    ) -> List[dict]:
+        """The macro panel (rates, inflation, spreads, VIX, …) over time."""
+        return self._get(
+            "/macro",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "start_date": start_date,
+                "end_date": end_date,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="macro_data",
+        )
+
+    def interest_rates(
+        self,
+        bank: str,
+        *,
+        scenario_id: Optional[str] = None,
+        start_date: Optional[DateLike] = None,
+        end_date: Optional[DateLike] = None,
+    ) -> List[dict]:
+        """Policy-rate history for a central ``bank`` (see :meth:`banks`)."""
+        return self._get(
+            "/macro/interest-rates",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "bank": bank,
+                "start_date": start_date,
+                "end_date": end_date,
+            },
+            unwrap="interest_rates",
+        )
+
+    def interest_rate_snapshot(
+        self, bank: str, *, scenario_id: Optional[str] = None, as_of: Optional[DateLike] = None
+    ) -> Any:
+        return self._get(
+            "/macro/interest-rates/snapshot",
+            params={"scenario_id": self._scenario(scenario_id), "bank": bank, "as_of": as_of},
+            unwrap="interest_rates",
+        )
+
+    def banks(self) -> List[str]:
+        """List the central banks with rate coverage."""
+        return self._get("/macro/interest-rates/banks", unwrap="banks")

david_data/resources/metadata.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .base import Resource
+
+
+class Metadata(Resource):
+    """API-level metadata: coverage, presets, themes, sectors, and audits."""
+
+    def sectors(self, *, scenario_id: Optional[str] = None) -> List[str]:
+        return self._get(
+            "/metadata/sectors",
+            params={"scenario_id": self._scenario(scenario_id)},
+            unwrap="sectors",
+        )
+
+    def scenario_themes(self) -> Any:
+        return self._get("/metadata/scenario-themes")
+
+    def scale_presets(self) -> Any:
+        return self._get("/metadata/scale-presets")
+
+    def financial_datasets_coverage(self) -> Any:
+        return self._get("/metadata/financial-datasets-coverage")
+
+    def institutional_readiness(self) -> Any:
+        return self._get("/metadata/institutional-readiness")
+
+    def synthetic_data_audit(self) -> Any:
+        return self._get("/metadata/synthetic-data-audit")
+
+    def empirical_calibration(self, *, panel_path: Optional[str] = None) -> Any:
+        return self._get(
+            "/metadata/empirical-calibration",
+            params={"panel_path": panel_path} if panel_path else None,
+        )