finzdata 0.1.0__py3-none-any.whl

finzdata/__init__.py

@@ -0,0 +1,371 @@
+from __future__ import annotations
+
+import datetime as dt
+import io
+import os
+from typing import Any, Optional
+
+import httpx
+import pandas as pd
+
+__version__ = "0.1.0"
+
+_DATE_COLUMNS = ("date", "ts", "start", "end", "filed")
+_DATE_COLUMNS = tuple(dict.fromkeys(tuple(_DATE_COLUMNS) + ("realtime_start",)))
+_DATE_COLUMNS = tuple(dict.fromkeys(tuple(_DATE_COLUMNS) + ("trade_date",)))
+# realtime_end stays text: the open vintage is 9999-12-31, outside pandas timestamp range
+
+
+class FinzError(Exception):
+    def __init__(self, status: int, detail: str):
+        super().__init__(f"{status}: {detail}")
+        self.status = int(status)
+        self.detail = str(detail)
+
+
+def _iso(value: Any) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, (dt.date, dt.datetime)):
+        return value.isoformat()
+    if isinstance(value, pd.Timestamp):
+        return value.isoformat()
+    return value
+
+
+def _clean(params: dict) -> dict:
+    out = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        out[key] = _iso(value)
+    return out
+
+
+class Client:
+    def __init__(self, api_key=None, base_url=None, http=None, timeout=60):
+        self.api_key = api_key if api_key is not None else os.environ.get("FINZDATA_API_KEY")
+        self.base_url = base_url if base_url is not None else (
+            os.environ.get("FINZDATA_URL") or "http://127.0.0.1:8787"
+        )
+        self.timeout = timeout
+        if http is not None:
+            self.http = http
+        else:
+            self.http = httpx.Client(base_url=self.base_url, timeout=timeout)
+
+    def _get(self, path: str, params: Optional[dict] = None):
+        response = self.http.get(
+            path,
+            params=_clean(params or {}),
+            headers={"X-API-Key": self.api_key},
+        )
+        if not (200 <= response.status_code < 300):
+            detail = None
+            try:
+                payload = response.json()
+                if isinstance(payload, dict):
+                    detail = payload.get("detail")
+            except Exception:
+                detail = None
+            if detail is None:
+                detail = response.text
+            if not isinstance(detail, str):
+                detail = str(detail)
+            raise FinzError(response.status_code, detail)
+        return response.json()
+
+    def _frame(self, path: str, params: Optional[dict] = None) -> pd.DataFrame:
+        payload = self._get(path, params)
+        rows = payload.get("data", []) if isinstance(payload, dict) else []
+        frame = pd.DataFrame(rows)
+        for column in _DATE_COLUMNS:
+            if column in frame.columns:
+                frame[column] = pd.to_datetime(frame[column])
+        return frame
+
+    def me(self) -> dict:
+        return self._get("/v1/me")
+
+    def datasets(self):
+        return self._frame("/v1/datasets", {})
+
+    def cot(self, report=None, code=None, market=None, start=None, end=None) -> pd.DataFrame:
+        return self._frame(
+            "/v1/cot",
+            {"report": report, "code": code, "market": market, "start": start, "end": end},
+        )
+
+    def cot_markets(self, report="legacy_fo"):
+        return self._frame("/v1/cot/markets", {"report": report})
+
+    def prices(self, symbol, start=None, end=None, adjust="splits") -> pd.DataFrame:
+        return self._frame(
+            "/v1/prices/daily",
+            {"symbol": symbol, "start": start, "end": end, "adjust": adjust},
+        )
+
+    def minutes(self, symbol, start=None, end=None, interval="1min", adjust="none") -> pd.DataFrame:
+        """Intraday bars. interval: 1min | 5min | 1hour. adjust: none | all (splits + dividends)."""
+        return self._frame(
+            "/v1/prices/minute",
+            {"symbol": symbol, "start": start, "end": end, "interval": interval, "adjust": adjust},
+        )
+
+    def actions(self, symbol) -> pd.DataFrame:
+        return self._frame("/v1/actions", {"symbol": symbol})
+
+    def fundamentals(self, ticker=None, cik=None, concept=None, as_of=None) -> pd.DataFrame:
+        return self._frame(
+            "/v1/fundamentals",
+            {"ticker": ticker, "cik": cik, "concept": concept, "as_of": as_of},
+        )
+
+
+_default: Optional[Client] = None
+
+
+def set_default_client(client: Optional[Client]) -> None:
+    global _default
+    _default = client
+
+
+def get_client() -> Client:
+    global _default
+    if _default is None:
+        _default = Client()
+    return _default
+
+
+def period_start(period, today=None):
+    if today is None:
+        today = dt.date.today()
+    if isinstance(today, dt.datetime):
+        today = today.date()
+    if period is None:
+        raise ValueError(f"invalid period: {period!r}")
+    text = str(period).strip().lower()
+    if text == "max":
+        return None
+    if text == "ytd":
+        return dt.date(today.year, 1, 1)
+    for suffix, days in (("wk", 7), ("mo", 31), ("d", 1), ("y", 366)):
+        if text.endswith(suffix):
+            number = text[: -len(suffix)]
+            if number.isdigit():
+                return today - dt.timedelta(days=days * int(number))
+    raise ValueError(f"invalid period: {period!r}")
+
+
+_HISTORY_COLUMNS = ["Open", "High", "Low", "Close", "Volume"]
+
+
+def _empty_history(index_name: str = "Date") -> pd.DataFrame:
+    index = pd.DatetimeIndex([], name=index_name)
+    return pd.DataFrame(columns=_HISTORY_COLUMNS, index=index)
+
+
+class Ticker:
+    def __init__(self, symbol, client=None):
+        self.ticker = str(symbol).upper()
+        self.client = client if client is not None else get_client()
+
+    def history(self, period="1mo", interval="1d", start=None, end=None, auto_adjust=True) -> pd.DataFrame:
+        if start is None:
+            start = period_start(period)
+        if interval == "1d":
+            frame = self.client.prices(
+                self.ticker,
+                start=start,
+                end=end,
+                adjust="all" if auto_adjust else "none",
+            )
+            index_name = "Date"
+        elif interval in _INTRADAY:
+            frame = self.client.minutes(
+                self.ticker,
+                start=start,
+                end=end,
+                interval=_INTRADAY[interval],
+                adjust="all" if auto_adjust else "none",
+            )
+            index_name = "Datetime"
+        else:
+            raise ValueError(f"invalid interval: {interval!r}")
+        return _normalize_history(frame, index_name)
+
+    @property
+    def dividends(self) -> pd.Series:
+        return self._action_series("dividend", "Dividends")
+
+    @property
+    def splits(self) -> pd.Series:
+        return self._action_series("split", "Stock Splits")
+
+    def _action_series(self, kind: str, name: str) -> pd.Series:
+        frame = self.client.actions(self.ticker)
+        index = pd.DatetimeIndex([], name="Date")
+        series = pd.Series([], dtype="float64", index=index, name=name)
+        if frame is None or frame.empty or "type" not in frame.columns:
+            return series
+        mask = frame["type"].astype(str).str.lower().str.contains(kind)
+        subset = frame[mask]
+        if subset.empty:
+            return series
+        dates = None
+        for column in ("date", "ts"):
+            if column in subset.columns:
+                dates = pd.to_datetime(subset[column])
+                break
+        if dates is None:
+            dates = pd.to_datetime(subset.index)
+        values = None
+        for column in ("value", "amount", "dividend", "split"):
+            if column in subset.columns:
+                values = subset[column]
+                break
+        if values is None:
+            numeric = [c for c in subset.columns if c not in ("type", "date", "ts")]
+            values = subset[numeric[0]] if numeric else pd.Series([1.0] * len(subset))
+        series = pd.Series(
+            pd.to_numeric(values, errors="coerce").to_numpy(),
+            index=pd.DatetimeIndex(dates, name="Date"),
+            name=name,
+        )
+        return series.sort_index()
+
+    @property
+    def actions(self) -> pd.DataFrame:
+        dividends = self.dividends
+        splits = self.splits
+        frame = pd.DataFrame({"Dividends": dividends, "Stock Splits": splits})
+        frame = frame.fillna(0.0)
+        frame.index = pd.DatetimeIndex(frame.index, name="Date")
+        return frame
+
+    def facts(self, concept=None, as_of=None) -> pd.DataFrame:
+        return self.client.fundamentals(ticker=self.ticker, concept=concept, as_of=as_of)
+
+
+def _normalize_history(frame: pd.DataFrame, index_name: str) -> pd.DataFrame:
+    if frame is None or frame.empty:
+        return _empty_history(index_name)
+    frame = frame.copy()
+    date_column = None
+    for column in ("date", "ts"):
+        if column in frame.columns:
+            date_column = column
+            break
+    if date_column is not None:
+        frame.index = pd.DatetimeIndex(pd.to_datetime(frame[date_column]), name=index_name)
+        frame = frame.drop(columns=[date_column])
+    else:
+        frame.index = pd.DatetimeIndex(pd.to_datetime(frame.index), name=index_name)
+    rename = {}
+    for column in frame.columns:
+        lowered = str(column).lower()
+        for target in _HISTORY_COLUMNS:
+            if lowered == target.lower():
+                rename[column] = target
+    frame = frame.rename(columns=rename)
+    for column in _HISTORY_COLUMNS:
+        if column not in frame.columns:
+            frame[column] = pd.Series(dtype="float64")
+    frame = frame[_HISTORY_COLUMNS]
+    return frame.sort_index()
+
+
+def _parse_tickers(tickers) -> list:
+    if isinstance(tickers, str):
+        parts = tickers.replace(",", " ").split()
+        return [part.upper() for part in parts]
+    return [str(ticker).upper() for ticker in tickers]
+
+
+_INTRADAY = {"1m": "1min", "5m": "5min", "60m": "1hour", "1h": "1hour"}
+
+
+def download(tickers, start=None, end=None, period="1mo", interval="1d", auto_adjust=True, client=None) -> pd.DataFrame:
+    symbols = _parse_tickers(tickers)
+    frames = {}
+    for symbol in symbols:
+        ticker = Ticker(symbol, client=client)
+        frames[symbol] = ticker.history(
+            period=period,
+            interval=interval,
+            start=start,
+            end=end,
+            auto_adjust=auto_adjust,
+        )
+    if not frames:
+        return pd.DataFrame()
+    combined = pd.concat(frames, axis=1)
+    combined.columns = combined.columns.swaplevel(0, 1)
+    combined = combined.sort_index(axis=1, level=0)
+    return combined.sort_index()
+
+
+def cot(**kw) -> pd.DataFrame:
+    return get_client().cot(**kw)
+
+
+# --- macro data (FRED/ALFRED, point-in-time) -------------------------------------------
+def _clean(params: dict) -> dict:
+    return {k: (v.isoformat() if hasattr(v, "isoformat") else v) for k, v in params.items() if v is not None}
+
+
+def _macro(self, series, start=None, end=None, vintage="latest", as_of=None) -> pd.DataFrame:
+    """Macro series. vintage: 'latest' (current values), 'first' (as first released) or 'all';
+    as_of='YYYY-MM-DD' returns only what was known on that date (point-in-time, Researcher+)."""
+    return self._frame("/v1/macro", _clean({"series": series, "start": start, "end": end, "vintage": vintage, "as_of": as_of}))
+
+
+def _macro_series(self, category=None) -> pd.DataFrame:
+    """Catalog of available macro series (id, title, units, frequency, category, ...)."""
+    return self._frame("/v1/macro/series", _clean({"category": category}))
+
+
+def _macro_calendar(self, start=None, end=None) -> pd.DataFrame:
+    """Upcoming and recent economic release dates."""
+    return self._frame("/v1/macro/calendar", _clean({"start": start, "end": end}))
+
+
+Client.macro = _macro
+Client.macro_series = _macro_series
+Client.macro_calendar = _macro_calendar
+
+
+def macro(series, **kw):
+    return get_client().macro(series, **kw)
+
+
+def _licensed(self, series_id, start=None, end=None) -> pd.DataFrame:
+    """Third-party licensed series (paid plans). Each row carries its `source` citation."""
+    return self._frame("/v1/licensed/series", _clean({"id": series_id, "start": start, "end": end}))
+
+
+def _licensed_catalog(self) -> pd.DataFrame:
+    """Licensed series, their owners, citations and availability."""
+    return self._frame("/v1/licensed/catalog", {})
+
+
+def _vix_futures(self, start=None, end=None) -> pd.DataFrame:
+    """Daily VIX futures settlements by expiry (paid plans)."""
+    return self._frame("/v1/licensed/vix-futures", _clean({"start": start, "end": end}))
+
+
+Client.licensed = _licensed
+Client.licensed_catalog = _licensed_catalog
+Client.vix_futures = _vix_futures
+
+
+def _model(self, what="latest", series=None, start=None, end=None):
+    """FinzData Quantitative Model (paid plans): what = latest | labels | nowcast | stress | catalog."""
+    if what not in ("latest", "labels", "nowcast", "stress", "catalog"):
+        raise ValueError("what must be latest, labels, nowcast, stress or catalog")
+    if what == "latest":
+        return self._get("/v1/model/latest", {})
+    return self._frame(f"/v1/model/{what}", _clean({"series": series, "start": start, "end": end}))
+
+
+Client.model = _model

finzdata-0.1.0.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: finzdata
+Version: 0.1.0
+Summary: FinzData market data client: yfinance-style prices plus COT, SEC fundamentals, point-in-time macro and more
+Project-URL: Homepage, https://finzdata.com
+Project-URL: Documentation, https://finzdata.com/docs
+Project-URL: Pricing, https://finzdata.com/pricing
+Project-URL: Status, https://finzdata.com/status
+Keywords: market data,stocks,yfinance,cot,sec,fred,finance,api
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5
+Requires-Dist: httpx>=0.24
+Requires-Dist: pyarrow>=12
+
+# finzdata
+
+Python client for the [FinzData](https://finzdata.com) market data API. It works like yfinance and adds
+the datasets yfinance doesn't have.
+
+```
+pip install finzdata
+```
+
+Get a free API key at https://api.finzdata.com/ and set `FINZDATA_API_KEY`.
+
+```python
+import finzdata as yf
+
+msft = yf.Ticker("MSFT")
+daily = msft.history(start="2020-01-01")                  # daily bars, split and dividend adjusted
+bars = msft.history(interval="5m", start="2026-10-01")    # 1m, 5m, 1h bars (Researcher+)
+both = yf.download(["SPY", "QQQ"], period="max")
+
+c = yf.Client()
+gold = c.cot(report="legacy_fo", market="GOLD")           # CFTC Commitments of Traders
+rev = c.fundamentals(ticker="AAPL", concept="Revenues", as_of="2025-06-30")   # SEC, point-in-time
+cpi = c.macro("CPIAUCSL", as_of="2022-06-30")             # US macro, as known on that date
+regime = c.model("latest")                                # FinzData Quantitative Model (Researcher+)
+hy = c.licensed("BAMLH0A0HYM2")                           # licensed third-party series (Researcher+)
+```
+
+## Datasets
+
+- US equity bars, daily (incl. delisted names) and intraday 1-minute, 5-minute and hourly
+- Splits and dividends
+- CFTC Commitments of Traders, all reports, since 1986
+- SEC XBRL fundamentals, as reported and point-in-time
+- US macro series with every vintage (FRED/ALFRED), plus a release calendar
+- FinzData Quantitative Model: macro regime labels, a nowcast and a market-stress probability
+- Licensed series: Moody's, University of Michigan, Case-Shiller, ICE BofA, Cboe (incl. the VIX futures curve)
+
+Free samples and the full file specification: https://finzdata.com/samples ·
+Pricing: https://finzdata.com/pricing · Data status: https://finzdata.com/status ·
+API reference: https://api.finzdata.com/docs
+
+Bulk downloads (Researcher and above): `POST /v1/batch`, then fetch the `download_url`.
+Full-history bundles and nightly updates: `GET /v1/bundles`.
+
+Data is provided under the FinzData subscriber licence; redistribution is prohibited.

finzdata-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+finzdata/__init__.py,sha256=epQ6sCN6c7LLbfSU27I8e4KzGiAO5LeRaDEvfngU7SM,13099
+finzdata-0.1.0.dist-info/METADATA,sha256=L-mwEwYtkE_vHHw3NNHJsxvEZJ1joUkJxtRiu2NVDb0,2825
+finzdata-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+finzdata-0.1.0.dist-info/top_level.txt,sha256=2NSdEKSomijSh8gY7wh4u2-oRqmt5Ou46AMCubaCv0M,9
+finzdata-0.1.0.dist-info/RECORD,,

finzdata-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

finzdata-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+finzdata