david-data 0.1.2

Official Python client for the David Data financial-data API (api.davidhf.com).

David Data — Python SDK

Official Python client for the David Data 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.

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.

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:

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:

export DAVID_DATA_API_KEY="sk_..."

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:

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. David builds and curates the library; browse it and pull data from any scenario:

for s in dd.scenarios.list(limit=10):
    print(s["id"], "-", s["name"])

# Inspect one
dd.scenarios.get(sid)
dd.scenarios.validation(sid)        # data-integrity report

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, validation
dd.metadata	sectors, scenario_themes, …

Dates accept either ISO strings ("2024-01-01") or datetime.date objects.

Point-in-time (no look-ahead): every dated endpoint takes a cutoff so you only see what was public as of a date. Use as_of on prices.snapshot, news.list, analyst.estimates, earnings.list, insiders.transactions, kpi_guidance, and corporate_actions.list; use report_period_lte on the statement and metric views (financials.*, financials.metrics, kpi_metrics, kpi_non_gaap). Use news.list(market_only=True) for just the market/macro coverage.

Errors & retries

All exceptions subclass DavidDataError. HTTP failures map to specific types:

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:

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