david-data 0.1.0__tar.gz

david_data-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Test
+        run: pytest -q

david_data-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish to PyPI
+
+# Publishes on a GitHub Release. Uses PyPI Trusted Publishing (OIDC) — no API
+# token secret required. Configure the trusted publisher once on PyPI (see
+# RELEASING.md), then cutting a release does the rest.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        default: testpypi
+        type: choice
+        options: [testpypi, pypi]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' || inputs.target == 'pypi'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/david-data
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/david-data
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

david_data-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store

david_data-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to `david-data` are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-06-24
+
+Initial release.
+
+- `DavidData` client over the David Data API (`https://api.davidhf.com`).
+- Resource groups: `prices`, `financials`, `company`, `news`, `filings`,
+  `earnings`, `analyst`, `events`, `insiders`, `institutional`, `index_funds`,
+  `corporate_actions`, `macro`, `scenarios`, `metadata`.
+- Data calls are keyed by `scenario_id` (a synthetic world). Set a default once
+  on the client or pass it per call; omitting it raises a clear error.
+- FMP-style returns (parsed JSON with the response envelope unwrapped) and an
+  optional `to_df()` pandas helper (`pip install david-data[pandas]`).
+- Typed exception hierarchy under `DavidDataError`; automatic retry of `429`
+  and transient `5xx` responses with exponential backoff (honours `Retry-After`).
+- `dd.get()` / `dd.post()` escape hatches for any endpoint.

david_data-0.1.0/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.

david_data-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,143 @@
+# 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/RELEASING.md

@@ -0,0 +1,59 @@
+# Releasing `david-data` to PyPI
+
+The repo publishes with **PyPI Trusted Publishing** (OIDC). No long-lived API
+token is stored anywhere — GitHub Actions mints a short-lived token at publish
+time. You configure the trust relationship once.
+
+## One-time setup
+
+### 1. Create the PyPI trusted publisher
+
+You can do this *before* the project exists on PyPI ("pending publisher").
+
+1. Log in to <https://pypi.org> → your account → **Publishing**.
+2. Under "Add a new pending publisher", enter:
+   - **PyPI Project Name:** `david-data`
+   - **Owner:** `David-Hedgefund`
+   - **Repository name:** `david-data-python`
+   - **Workflow name:** `publish.yml`
+   - **Environment name:** `pypi`
+3. Save. Repeat on <https://test.pypi.org> with environment `testpypi` if you
+   want a staging target.
+
+### 2. Create the GitHub environments
+
+In the GitHub repo → **Settings → Environments**, create environments named
+`pypi` (and optionally `testpypi`). No secrets needed. Optionally add required
+reviewers so a release waits for manual approval.
+
+## Cutting a release
+
+1. Bump the version in **two** places (keep them in sync):
+   - `pyproject.toml` → `[project] version`
+   - `src/david_data/_version.py` → `__version__`
+2. Update `CHANGELOG.md`.
+3. Commit and tag:
+   ```bash
+   git commit -am "Release v0.1.1"
+   git tag v0.1.1
+   git push && git push --tags
+   ```
+4. On GitHub → **Releases → Draft a new release**, choose the tag, publish.
+5. The `publish.yml` workflow builds, runs `twine check`, and publishes to PyPI.
+
+## Dry run to TestPyPI
+
+GitHub → **Actions → Publish to PyPI → Run workflow**, choose `testpypi`. Then:
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ david-data
+```
+
+## Build locally
+
+```bash
+python -m pip install build twine
+python -m build          # -> dist/david_data-*.whl and *.tar.gz
+twine check dist/*
+```

david_data-0.1.0/examples/quickstart.py

@@ -0,0 +1,44 @@
+"""Minimal end-to-end example.
+
+Run against the live API:
+    export DAVID_DATA_API_KEY="sk_..."
+    python examples/quickstart.py
+
+Or against a local dev server:
+    export DAVID_DATA_API_KEY="dev_key_123"
+    export DAVID_DATA_BASE_URL="http://localhost:8099"
+    python examples/quickstart.py
+"""
+
+from david_data import DavidData, to_df
+
+
+def main() -> None:
+    with DavidData() as dd:
+        print("health:", dd.health())
+
+        # Every data call is keyed by a scenario_id — grab one to work with.
+        scenarios = dd.scenarios.list(limit=1)
+        if not scenarios:
+            print("no scenarios available on this server")
+            return
+        sid = scenarios[0]["id"]
+        print("\nusing scenario:", sid, "-", scenarios[0].get("name"))
+
+        ticker = (dd.prices.tickers(scenario_id=sid) or ["AAPL"])[0]
+
+        bars = dd.prices.get(ticker, scenario_id=sid, limit=5)
+        print(f"\n{len(bars)} price bars for {ticker}; first:")
+        print(bars[0] if bars else "(none)")
+
+        income = dd.financials.income_statements(ticker, scenario_id=sid, period="quarterly", limit=3)
+        print("\nincome statements as a DataFrame:")
+        print(to_df(income))
+
+        print("\nlatest news headlines:")
+        for article in dd.news.list(ticker=ticker, scenario_id=sid, limit=3):
+            print(" -", article.get("title") or article.get("headline"))
+
+
+if __name__ == "__main__":
+    main()