david-data 0.1.0__py3-none-any.whl

david_data/resources/ownership.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .base import Resource
+
+DateLike = Any
+
+
+class Insiders(Resource):
+    """Insider trading: Form-4 style trades and aggregated transactions."""
+
+    def trades(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        ticker: Optional[str] = None,
+        name: Optional[str] = None,
+        transaction_type: Optional[str] = None,
+        filing_date_gte: Optional[DateLike] = None,
+        filing_date_lte: Optional[DateLike] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/insider-trades",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "name": name,
+                "transaction_type": transaction_type,
+                "filing_date_gte": filing_date_gte,
+                "filing_date_lte": filing_date_lte,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="insider_trades",
+        )
+
+    def transactions(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        ticker: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/insider-transactions",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="insider_transactions",
+        )
+
+
+class Institutional(Resource):
+    """13F institutional holdings and the investor directory."""
+
+    def holdings(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        ticker: Optional[str] = None,
+        filer_cik: Optional[str] = None,
+        report_period_gte: Optional[DateLike] = None,
+        report_period_lte: Optional[DateLike] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/institutional-holdings",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "filer_cik": filer_cik,
+                "report_period_gte": report_period_gte,
+                "report_period_lte": report_period_lte,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="institutional_holdings",
+        )
+
+    def investors(self, *, scenario_id: Optional[str] = None, name: Optional[str] = None) -> Any:
+        return self._get(
+            "/institutional-holdings/investors",
+            params={"scenario_id": self._scenario(scenario_id), "name": name},
+            unwrap="investors",
+        )
+
+    def tickers(self, *, scenario_id: Optional[str] = None) -> List[str]:
+        return self._get(
+            "/institutional-holdings/tickers",
+            params={"scenario_id": self._scenario(scenario_id)},
+            unwrap="tickers",
+        )
+
+
+class IndexFunds(Resource):
+    """Index-fund constituents and the reverse holding lookup."""
+
+    def list(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        ticker: Optional[str] = None,
+        holding: Optional[str] = None,
+        as_of: Optional[DateLike] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> Any:
+        return self._get(
+            "/index-funds",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "holding": holding,
+                "as_of": as_of,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="index_funds",
+        )
+
+    def tickers(self) -> List[str]:
+        return self._get("/index-funds/tickers", unwrap="tickers")
+
+
+class CorporateActions(Resource):
+    """Splits, dividends, and other corporate actions."""
+
+    def list(
+        self,
+        *,
+        scenario_id: Optional[str] = None,
+        ticker: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/corporate-actions",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="corporate_actions",
+        )

david_data/resources/prices.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .base import Resource
+
+DateLike = Any  # str ("YYYY-MM-DD") or datetime.date
+
+
+class Prices(Resource):
+    """Daily OHLCV price history, point-in-time snapshots, and market-wide views."""
+
+    def get(
+        self,
+        ticker: str,
+        *,
+        scenario_id: Optional[str] = None,
+        interval: str = "day",
+        start_date: Optional[DateLike] = None,
+        end_date: Optional[DateLike] = None,
+        include_components: bool = False,
+        limit: int = 1000,
+        offset: int = 0,
+    ) -> List[dict]:
+        """Return a list of OHLCV bars for ``ticker``.
+
+        ``include_components=True`` adds the synthetic return-decomposition fields.
+        For real data (``scenario_id="real"``) intraday intervals such as
+        ``"minute"``, ``"5minute"`` and ``"hour"`` are also accepted.
+        """
+        return self._get(
+            "/prices",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "ticker": ticker,
+                "interval": interval,
+                "start_date": start_date,
+                "end_date": end_date,
+                "include_components": include_components,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="prices",
+        )
+
+    def snapshot(self, ticker: str, *, as_of: DateLike, scenario_id: Optional[str] = None) -> dict:
+        """Return the single price bar in effect for ``ticker`` on ``as_of``."""
+        return self._get(
+            "/prices/snapshot",
+            params={"scenario_id": self._scenario(scenario_id), "ticker": ticker, "as_of": as_of},
+            unwrap="snapshot",
+        )
+
+    def market_snapshot(
+        self,
+        *,
+        as_of: Optional[DateLike] = None,
+        scenario_id: Optional[str] = None,
+        limit: int = 500,
+        offset: int = 0,
+    ) -> dict:
+        """Return a cross-section of the latest prices across the whole universe."""
+        return self._get(
+            "/prices/snapshot/market",
+            params={
+                "scenario_id": self._scenario(scenario_id),
+                "as_of": as_of,
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+
+    def tickers(self, *, scenario_id: Optional[str] = None) -> List[str]:
+        """List every ticker with price coverage in the scenario."""
+        return self._get(
+            "/prices/tickers",
+            params={"scenario_id": self._scenario(scenario_id)},
+            unwrap="tickers",
+        )

david_data/resources/scenarios.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .base import Resource
+
+DateLike = Any
+
+
+class Scenarios(Resource):
+    """Discover and generate scenarios (synthetic worlds).
+
+    Every data call takes a ``scenario_id``. List the available worlds here, or
+    generate new ones on demand, then pass the id to the other resource groups.
+    """
+
+    def list(
+        self,
+        *,
+        status: Optional[str] = None,
+        path_mode: Optional[str] = None,
+        min_ticker_count: Optional[int] = None,
+        max_scenario_day_count: Optional[int] = None,
+        healthy_only: bool = False,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[dict]:
+        return self._get(
+            "/scenarios",
+            params={
+                "status": status,
+                "path_mode": path_mode,
+                "min_ticker_count": min_ticker_count,
+                "max_scenario_day_count": max_scenario_day_count,
+                "healthy_only": healthy_only,
+                "limit": limit,
+                "offset": offset,
+            },
+            unwrap="scenarios",
+        )
+
+    def get(self, scenario_id: str) -> dict:
+        return self._get(f"/scenarios/{scenario_id}", unwrap="scenario")
+
+    def manifest(self, scenario_id: str) -> dict:
+        return self._get(f"/scenarios/{scenario_id}/manifest", unwrap="manifest")
+
+    def validation(self, scenario_id: str) -> dict:
+        return self._get(f"/scenarios/{scenario_id}/validation", unwrap="validation_report")
+
+    def dataset_quality(
+        self,
+        scenario_id: str,
+        *,
+        ticker: Optional[str] = None,
+        sample_limit: int = 5,
+        offset: int = 0,
+    ) -> dict:
+        return self._get(
+            f"/scenarios/{scenario_id}/dataset-quality",
+            params={"ticker": ticker, "sample_limit": sample_limit, "offset": offset},
+        )
+
+    # -- generation -------------------------------------------------------
+    def create(self, *, start_date: DateLike, **options: Any) -> dict:
+        """Create a single scenario. See the API docs for the full option set
+        (``ticker_count``, ``scenario_theme``, ``path_mode``, ``seed``, …)."""
+        return self._post("/scenarios", json={"start_date": start_date, **options})
+
+    def bulk_generate(self, *, start_date: DateLike, count: int = 1, **options: Any) -> dict:
+        return self._post(
+            "/scenarios/bulk", json={"start_date": start_date, "count": count, **options}
+        )
+
+    def generate_library(self, *, start_date: DateLike, count: int = 24, **options: Any) -> dict:
+        return self._post(
+            "/scenarios/library", json={"start_date": start_date, "count": count, **options}
+        )

david_data-0.1.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: david-data
+Version: 0.1.0
+Summary: Official Python client for the David Data financial-data API (api.davidhf.com).
+Project-URL: Homepage, https://davidhf.com
+Project-URL: Documentation, https://api.davidhf.com/docs
+Project-URL: Source, https://github.com/davidhf/david-data-python
+Author-email: David Data <investors@davidhf.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,david-data,finance,fundamentals,market-data,stocks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# David Data — Python SDK
+
+Official Python client for the [David Data](https://davidhf.com) financial-data
+API (`https://api.davidhf.com`). One consistent interface for **real** market
+data and **synthetic** scenarios — prices, fundamentals, filings, news,
+earnings, analyst & insider data, 13F holdings, and macro series.
+
+```bash
+pip install david-data           # core (httpx only)
+pip install david-data[pandas]   # + DataFrame helpers
+```
+
+## Quickstart
+
+Every data call is keyed by a **`scenario_id`** — a synthetic world. Pick one,
+then pull data from it.
+
+```python
+from david_data import DavidData
+
+dd = DavidData(api_key="sk_...")        # or set DAVID_DATA_API_KEY
+
+# 1. Find a scenario
+scenario = dd.scenarios.list(limit=1)[0]
+sid = scenario["id"]
+print(scenario["name"])
+
+# 2. Pull data from it
+bars = dd.prices.get("AAPL", scenario_id=sid, start_date="2024-01-01")
+income = dd.financials.income_statements("AAPL", scenario_id=sid, period="quarterly", limit=5)
+news = dd.news.list(ticker="AAPL", scenario_id=sid, limit=10)
+
+print(bars[0])      # {'ticker': 'AAPL', 'open': ..., 'close': ..., 'volume': ...}
+```
+
+Repeating `scenario_id=` on every call gets old — set it once on the client and
+omit it thereafter:
+
+```python
+dd = DavidData(api_key="sk_...", scenario_id=sid)
+dd.prices.get("AAPL")                    # uses the client default
+dd.prices.get("AAPL", scenario_id="other-world")   # override per call
+```
+
+Calling a data endpoint with no `scenario_id` (and no client default) raises a
+clear error instead of guessing.
+
+Set the key once via the environment and you can skip the argument entirely:
+
+```bash
+export DAVID_DATA_API_KEY="sk_..."
+```
+
+```python
+from david_data import DavidData
+dd = DavidData()
+```
+
+## Returns
+
+Methods return parsed JSON — a `list` of record dicts for collection endpoints,
+a `dict` for single-object endpoints — exactly like the underlying API, with the
+envelope unwrapped for you (`dd.prices.get(...)` gives you the list of bars
+directly). Convert any result to a DataFrame:
+
+```python
+from david_data import to_df
+df = to_df(dd.prices.get("AAPL", start_date="2024-01-01"))
+```
+
+## Scenarios
+
+A scenario is a self-contained synthetic world with its own universe of
+companies, prices, fundamentals, filings, and events. Browse what's available,
+or generate new ones:
+
+```python
+for s in dd.scenarios.list(limit=10):
+    print(s["id"], "-", s["name"])
+
+# Inspect one
+dd.scenarios.get(sid)
+dd.scenarios.manifest(sid)          # tickers, date range, coverage
+
+# Generate your own
+created = dd.scenarios.create(start_date="2024-01-01", ticker_count=25)
+```
+
+## What you can pull
+
+| Group | Examples |
+|-------|----------|
+| `dd.prices` | `get`, `snapshot`, `market_snapshot`, `tickers` |
+| `dd.financials` | `income_statements`, `balance_sheets`, `cash_flow_statements`, `metrics`, `segments`, `as_reported`, `kpi_metrics`, `screener`, `line_items` |
+| `dd.company` | `list`, `facts`, `tickers`, `ciks` |
+| `dd.news` / `dd.filings` | `list`, `get` / `list`, `items`, `types` |
+| `dd.earnings` / `dd.analyst` | `list`, `calendar` / `estimates`, `notes` |
+| `dd.insiders` / `dd.institutional` | `trades`, `transactions` / `holdings`, `investors` |
+| `dd.index_funds` / `dd.corporate_actions` | `list` |
+| `dd.macro` | `series`, `interest_rates`, `banks` |
+| `dd.events` | `timeline` |
+| `dd.scenarios` | `list`, `get`, `manifest`, `create`, `bulk_generate`, `generate_library` |
+| `dd.metadata` | `sectors`, `scenario_themes`, `scale_presets`, … |
+
+Dates accept either ISO strings (`"2024-01-01"`) or `datetime.date` objects.
+
+## Errors & retries
+
+All exceptions subclass `DavidDataError`. HTTP failures map to specific types:
+
+```python
+from david_data import DavidData, NotFoundError, RateLimitError
+
+dd = DavidData()
+try:
+    dd.prices.get("AAPL")
+except RateLimitError as e:
+    print("slow down; retry after", e.retry_after)
+except NotFoundError:
+    print("no such ticker / scenario")
+```
+
+The client automatically retries `429` and transient `5xx` responses with
+exponential backoff (honouring `Retry-After`); tune with `max_retries=`.
+
+## Escape hatch
+
+Any endpoint not yet wrapped is reachable directly:
+
+```python
+dd.get("/metadata/institutional-readiness")
+dd.post("/financials/search/screener", json={"scenario_id": "real", "filters": [...]})
+```
+
+## Anything else
+
+- `with DavidData() as dd: ...` closes the connection pool on exit.
+- Bring your own `httpx.Client` via `http_client=` for proxies/custom transport.
+- Full endpoint reference: <https://api.davidhf.com/docs>
+
+## License
+
+MIT

david_data-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+david_data/__init__.py,sha256=cZsNzJYDRIiqqUdeZICu0lK_MmMkg-76HH4ISdOTXjE,912
+david_data/_http.py,sha256=OmkuIhw0pBe3t2vEe5gSc_iAa3B9Vod40UK-oHYsy18,5457
+david_data/_pandas.py,sha256=BMVSKSmeJSRK9NzdRYfbHoZ19JD8U7SR1_VAafW5FnU,1030
+david_data/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+david_data/client.py,sha256=_s4h9bQumfJAm903-l3GyxJ71aYVH4HdmNpF_Om71jo,4784
+david_data/errors.py,sha256=ccMpQ2TtTnZf6ih2gkDXgOJE0MEAmJWsboFxSRiD32E,3654
+david_data/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+david_data/resources/__init__.py,sha256=QKO9OzJN6_psVX4W-qLjm_L8o9AG5uZCyAPVeO0JCXg,602
+david_data/resources/base.py,sha256=WdAP9OVr7-NGZ7659SHNzP1W4qV7pO5_X_22QYhMmDU,2029
+david_data/resources/company.py,sha256=v9cB3OM7V-Ds7Frwma0Cs4VMbkhoefC3MXsRYOSeA08,1713
+david_data/resources/documents.py,sha256=BKE5mcxuP2ijWKPnmgG9mCvLJb4xnXGI-aIxPj3iQN8,3988
+david_data/resources/estimates.py,sha256=VMZTyoo-1j65o4AU9um3uFwnyQWEs8GfuPbNIRVsqLQ,3676
+david_data/resources/financials.py,sha256=pEVXe1boq_iWnBoROlt0pm1vVAMT0XQKb9O3wpg3L1w,8731
+david_data/resources/macro.py,sha256=Vp7BDFUUmtcfVSP2opmYEsWbVr825tWXtYsk3_kLPQ8,2002
+david_data/resources/metadata.py,sha256=7pnjXAbimuCdq63w2MsxDuCQjJP1I5YqkRCZwhBEBfY,1195
+david_data/resources/ownership.py,sha256=OVGt-ELp0jPi5v2mmOE73qnrZt6H-_QOBjs_kQeZcdI,4484
+david_data/resources/prices.py,sha256=hHVRTrQPTMIGx7pMe-Pk7U_uO0trowCJ9t_fqAusRDI,2608
+david_data/resources/scenarios.py,sha256=Vr0Gjb7wHqldcFN_ilXQ6DCDFNMz5LGU5mnDq6rrBt0,2746
+david_data-0.1.0.dist-info/METADATA,sha256=Bm5BqSYpPHu599xBBPxo7d2zO0QAeIQKZb3Hk29KKGE,5671
+david_data-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+david_data-0.1.0.dist-info/licenses/LICENSE,sha256=IwuRgB1JQvlTCQacMywgbEOXFzMhXn9MROVryVK2iXo,1067
+david_data-0.1.0.dist-info/RECORD,,

david_data-0.1.0.dist-info/WHEEL

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

david_data-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Data
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.