clarifindata 0.2.5__py3-none-any.whl

clarifindata/__init__.py

@@ -0,0 +1,30 @@
+"""clarifindata — Python client for the 金晰數據 Taiwan-stock data API.
+
+    from clarifindata import Client, datasets
+    cfd = Client(api_key="cfd_demo_free_0001")
+    df = cfd.get(datasets.TaiwanStockPrice, stock_id="2330",
+                 start="2026-04-01", as_df=True)
+
+Concurrency (quant default):
+
+    import asyncio
+    from clarifindata import AsyncClient, datasets
+    async def main():
+        async with AsyncClient(api_key="...") as cfd:
+            out = await asyncio.gather(*[
+                cfd.get(datasets.TaiwanStockPrice, stock_id=s) for s in ("2330", "2317")])
+"""
+from __future__ import annotations
+
+from . import datasets
+from .client import AsyncClient, Client, __version__
+from .datasets import DATASET_ROW_TYPES, DatasetRow, Row
+from .errors import (AuthError, ClarifindataError, NotFoundError, RateLimitError,
+                     TierError, ValidationError)
+
+__all__ = [
+    "Client", "AsyncClient", "datasets", "__version__",
+    "DatasetRow", "Row", "DATASET_ROW_TYPES",
+    "ClarifindataError", "AuthError", "TierError", "RateLimitError",
+    "NotFoundError", "ValidationError",
+]

clarifindata/client.py

@@ -0,0 +1,489 @@
+"""clarifindata Python client — sync (`Client`) and async (`AsyncClient`).
+
+    from clarifindata import Client, datasets
+    cfd = Client(api_key="cfd_demo_free_0001")
+    df = cfd.get(datasets.TaiwanStockPrice, stock_id="2330", start="2026-04-01", as_df=True)
+
+Features: automatic retry (429/5xx, honours Retry-After), rate-limit awareness,
+DataFrame output, date-chunked full-history streaming, optional disk cache,
+typed errors, and an AsyncClient with the same surface.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import time
+from datetime import date, datetime
+from typing import Any, Iterator
+
+import httpx
+
+from . import datasets as _ds
+from .errors import (AuthError, ClarifindataError, NotFoundError, RateLimitError,
+                     TierError, ValidationError)
+
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("clarifindata")
+except Exception:  # not installed (running from source)
+    __version__ = "0.0.0+src"
+
+log = logging.getLogger("clarifindata")
+DEFAULT_BASE_URL = "https://api.clarifindata.com"
+ROW_CAP = 10000               # server hard cap per request
+_RETRY_STATUS = {429, 500, 502, 503, 504}
+
+
+# ───────────────────────── shared helpers ─────────────────────────
+def _mask(key: str) -> str:
+    return f"{key[:8]}…{key[-2:]}" if len(key) > 10 else "***"
+
+
+def _backoff(attempt: int, base: float, retry_after: float | None) -> float:
+    if retry_after is not None:
+        return retry_after
+    # exponential + light deterministic jitter (no global RNG dependency)
+    return min(60.0, base * (2 ** attempt)) * (1.0 + 0.1 * (attempt % 3))
+
+
+def _suggest(status: int, dataset: str | None) -> str:
+    if status in (401,):
+        return "Check your api_key (Authorization: Bearer <key>)."
+    if status == 403:
+        tier = _ds.DATASET_TIERS.get(dataset or "", "?")
+        return f"This needs a higher tier (dataset '{dataset}' requires '{tier}'). Upgrade or use a free dataset."
+    if status == 404:
+        return "Unknown dataset/endpoint — see clarifindata.datasets.ALL or cfd.catalog()."
+    if status in (400, 422):
+        return "Bad params — check the dataset name (clarifindata.datasets.*), date format (YYYY-MM-DD), and limit ≤ 10000."
+    if status == 429:
+        return "Rate limit — the client retries automatically; lower concurrency or upgrade tier."
+    return "See https://clarifindata.com/docs"
+
+
+def _err_from_response(r: httpx.Response, dataset: str | None) -> ClarifindataError:
+    try:
+        detail = r.json().get("detail")
+    except Exception:
+        detail = (r.text or "")[:200]
+    kw = dict(dataset=dataset, status=r.status_code, detail=detail,
+              suggestion=_suggest(r.status_code, dataset))
+    s = r.status_code
+    if s == 403:
+        return TierError("Forbidden", **kw)
+    if s == 401:
+        return AuthError("Unauthorized", **kw)
+    if s == 404:
+        return NotFoundError("Not found", **kw)
+    if s == 429:
+        ra = r.headers.get("retry-after")
+        return RateLimitError("Rate limited", retry_after=float(ra) if ra else None, **kw)
+    if s in (400, 422):
+        return ValidationError("Invalid request", **kw)
+    return ClarifindataError("HTTP error", **kw)
+
+
+def _validate_dataset(dataset: str) -> None:
+    if dataset not in _ds.ALL:
+        # offer a close match for typos
+        import difflib
+        near = difflib.get_close_matches(dataset, _ds.ALL, n=1)
+        hint = f" Did you mean '{near[0]}'?" if near else ""
+        raise ValidationError(f"Unknown dataset '{dataset}'.{hint}",
+                              dataset=dataset,
+                              suggestion="Use clarifindata.datasets.* for valid names.")
+
+
+def _params(stock_id, start, end, limit, cursor=None) -> dict[str, Any]:
+    p: dict[str, Any] = {"limit": limit}
+    if stock_id is not None:
+        p["stock_id"] = stock_id
+    if start is not None:
+        p["start"] = str(start)
+    if end is not None:
+        p["end"] = str(end)
+    if cursor is not None:
+        p["cursor"] = cursor
+    return p
+
+
+def _to_df(rows: list[dict[str, Any]]):
+    try:
+        import pandas as pd
+    except ImportError as e:
+        raise ClarifindataError(
+            "pandas not installed", suggestion="pip install 'clarifindata[pandas]'") from e
+    return pd.DataFrame(rows)
+
+
+def _cache_path(cache_dir: str, method: str, url: str, params: dict) -> str:
+    key = hashlib.sha256(f"{method}{url}{sorted(params.items())}".encode()).hexdigest()
+    return os.path.join(cache_dir, key + ".json")
+
+
+def _month_chunks(since: date, until: date):
+    """Yield (chunk_start, chunk_end) spanning since..until, one calendar year
+    each — small enough to stay under the 10000-row cap for one stock."""
+    cur = since
+    while cur <= until:
+        end = min(date(cur.year, 12, 31), until)
+        yield cur, end
+        cur = date(cur.year + 1, 1, 1)
+
+
+def _as_date(d) -> date:
+    if isinstance(d, date):
+        return d
+    return datetime.strptime(str(d), "%Y-%m-%d").date()
+
+
+# ───────────────────────── sync client ─────────────────────────
+class Client:
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 30.0, max_retries: int = 4, backoff_base: float = 0.5,
+                 cache_dir: str | None = None, cache_ttl: float = 86400.0,
+                 warn_rate_limit_pct: float = 80.0) -> None:
+        if not api_key:
+            raise ValueError("api_key is required (get a free key at clarifindata.com/signup)")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.backoff_base = backoff_base
+        self.cache_dir = cache_dir
+        self.cache_ttl = cache_ttl
+        self.warn_rate_limit_pct = warn_rate_limit_pct
+        self.rate_limit_limit: int | None = None
+        self.rate_limit_remaining: int | None = None
+        self.tier: str | None = None
+        if cache_dir:
+            os.makedirs(cache_dir, exist_ok=True)
+        try:
+            self._http = httpx.Client(base_url=self.base_url, timeout=timeout, http2=True,
+                                      headers=self._headers())
+        except Exception:  # h2 not installed → HTTP/1.1
+            self._http = httpx.Client(base_url=self.base_url, timeout=timeout,
+                                      headers=self._headers())
+
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}",
+                "User-Agent": f"clarifindata-py/{__version__}"}
+
+    # lifecycle
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def close(self) -> None:
+        if getattr(self, "_http", None) is not None:
+            self._http.close()
+
+    def __repr__(self) -> str:
+        rem = self.rate_limit_remaining
+        return (f"Client(base_url={self.base_url!r}, key={_mask(self.api_key)}, "
+                f"tier={self.tier}, rate_limit_remaining={rem})")
+
+    # core request with retry + rate-limit tracking + cache
+    def _request(self, method: str, path: str, *, params: dict | None = None,
+                 json_body: dict | None = None, dataset: str | None = None) -> dict:
+        params = params or {}
+        cache_file = None
+        if self.cache_dir and method == "GET":
+            cache_file = _cache_path(self.cache_dir, method, path, params)
+            if os.path.exists(cache_file) and (time.time() - os.path.getmtime(cache_file)) < self.cache_ttl:
+                log.debug("cache hit %s", path)
+                with open(cache_file) as f:
+                    return json.load(f)
+        last: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                log.debug("%s %s params=%s (attempt %d)", method, path, params, attempt)
+                r = self._http.request(method, path, params=params, json=json_body)
+                self._track_rate_limit(r)
+                if r.status_code in _RETRY_STATUS and attempt < self.max_retries:
+                    ra = r.headers.get("retry-after")
+                    wait = _backoff(attempt, self.backoff_base, float(ra) if ra else None)
+                    log.warning("HTTP %d on %s — retrying in %.1fs", r.status_code, path, wait)
+                    time.sleep(wait)
+                    continue
+                if r.status_code >= 400:
+                    raise _err_from_response(r, dataset)
+                body = r.json()
+                if cache_file is not None:
+                    with open(cache_file, "w") as f:
+                        json.dump(body, f)
+                return body
+            except (httpx.TimeoutException, httpx.TransportError) as e:
+                last = e
+                if attempt < self.max_retries:
+                    wait = _backoff(attempt, self.backoff_base, None)
+                    log.warning("network error on %s (%s) — retrying in %.1fs", path, e, wait)
+                    time.sleep(wait)
+                    continue
+                raise ClarifindataError(f"network error after {self.max_retries} retries",
+                                        dataset=dataset, suggestion="Check connectivity / base_url.") from e
+        raise ClarifindataError("request failed", dataset=dataset) from last
+
+    def _track_rate_limit(self, r: httpx.Response) -> None:
+        h = r.headers
+        if "x-ratelimit-limit" in h:
+            try:
+                self.rate_limit_limit = int(h["x-ratelimit-limit"])
+                self.rate_limit_remaining = int(h["x-ratelimit-remaining"])
+                self.tier = h.get("x-ratelimit-tier", self.tier)
+                used_pct = 100 * (1 - self.rate_limit_remaining / max(1, self.rate_limit_limit))
+                if used_pct >= self.warn_rate_limit_pct:
+                    log.warning("rate limit %.0f%% used (%d/%d remaining this window)",
+                                used_pct, self.rate_limit_remaining, self.rate_limit_limit)
+            except (ValueError, TypeError):
+                pass
+
+    # public API
+    def catalog(self) -> list[dict[str, Any]]:
+        """Full dataset catalog (coverage, tier, category)."""
+        return self._request("GET", "/v1/data").get("datasets", [])
+
+    def get(self, dataset: str, *, stock_id: str | None = None,
+            start: date | str | None = None, end: date | str | None = None,
+            limit: int = 1000, as_df: bool = False):
+        """Fetch rows from `dataset`. Returns list[dict], or a DataFrame if
+        as_df=True. Warns if the result is truncated at `limit` (raise it or use
+        iter_history for full ranges)."""
+        _validate_dataset(dataset)
+        if limit > ROW_CAP:
+            raise ValidationError(f"limit {limit} exceeds server cap {ROW_CAP}",
+                                  dataset=dataset, suggestion="Use iter_history() to stream large ranges.")
+        body = self._request("GET", f"/v1/data/{dataset}",
+                             params=_params(stock_id, start, end, limit), dataset=dataset)
+        rows = body.get("data", [])
+        if len(rows) == limit and body.get("next_cursor") is None:
+            log.warning("'%s' returned exactly limit=%d rows — result is likely TRUNCATED. "
+                        "Raise limit or use iter_history().", dataset, limit)
+        return _to_df(rows) if as_df else rows
+
+    def _pull_window(self, dataset: str, *, stock_id=None, start=None, end=None) -> list:
+        """Fully drain one (stock_id, start, end) window by following the server's
+        keyset `next_cursor` until it is null. Returns all rows as one list[dict].
+        This is what lets unbounded datasets (e.g. WarrantInfo, ~126k rows) be
+        collected despite the per-request ROW_CAP."""
+        out: list[dict[str, Any]] = []
+        cursor: str | None = None
+        while True:
+            body = self._request("GET", f"/v1/data/{dataset}",
+                                 params=_params(stock_id, start, end, ROW_CAP, cursor),
+                                 dataset=dataset)
+            out.extend(body.get("data", []))
+            cursor = body.get("next_cursor")
+            if not cursor:
+                return out
+
+    def iter_history(self, dataset: str, *, stock_id: str | None = None,
+                     since: date | str | None = None, until: date | str | None = None,
+                     as_df: bool = False) -> Iterator:
+        """Stream a full date range in year-sized chunks (auto-paginates around
+        the 10000-row cap). Yields one batch (list[dict] or DataFrame) per chunk.
+
+        When `since` is None (e.g. reference/realtime datasets with no date axis),
+        skips date chunking and yields a single batch capped at ROW_CAP."""
+        _validate_dataset(dataset)
+        if since is None:
+            # No date axis: drain the whole dataset via keyset cursor (handles
+            # datasets larger than ROW_CAP, e.g. WarrantInfo).
+            rows = self._pull_window(dataset, stock_id=stock_id)
+            if rows:
+                yield _to_df(rows) if as_df else rows
+            return
+        s = _as_date(since)
+        u = _as_date(until) if until else date.today()
+        for cs, ce in _month_chunks(s, u):
+            rows = self._pull_window(dataset, stock_id=stock_id, start=cs, end=ce)
+            if rows:
+                yield _to_df(rows) if as_df else rows
+
+    def history(self, dataset: str, **kw) -> list[dict[str, Any]]:
+        """Convenience: fully materialise iter_history into one list (or DataFrame).
+
+        `since` is optional: omit it for datasets with no date axis (reference/
+        realtime) and it behaves like get(dataset, limit=ROW_CAP)."""
+        as_df = kw.pop("as_df", False)
+        out: list[dict[str, Any]] = []
+        for batch in self.iter_history(dataset, **kw):
+            out.extend(batch)
+        return _to_df(out) if as_df else out
+
+    def bulk_pull(self, datasets: list[str], *, start: date | str | None = None,
+                  end: date | str | None = None, stock_id: str | None = None,
+                  as_df: bool = False) -> dict[str, Any]:
+        """Fetch several datasets for the same window; rate-limit-aware (pauses
+        if the window is nearly exhausted). Returns {dataset: rows|DataFrame}."""
+        out: dict[str, Any] = {}
+        for d in datasets:
+            if self.rate_limit_remaining is not None and self.rate_limit_remaining < 5:
+                log.warning("rate limit nearly exhausted — pausing 5s")
+                time.sleep(5)
+            rows = self._pull_window(d, stock_id=stock_id, start=start, end=end)
+            out[d] = _to_df(rows) if as_df else rows
+        return out
+
+    def ask(self, question: str, *, as_df: bool = False):
+        """Natural-language → SQL query (Plus tier only)."""
+        try:
+            body = self._request("POST", "/v1/ask", json_body={"question": question})
+        except TierError as e:
+            raise TierError("ask() requires the Plus tier", status=403,
+                            suggestion="Upgrade to Plus, or use get() with explicit params.") from e
+        return _to_df(body.get("data", [])) if as_df else body
+
+
+# ───────────────────────── async client ─────────────────────────
+class AsyncClient:
+    """Async mirror of Client — same surface, for concurrent fetches.
+
+        async with AsyncClient(api_key=...) as cfd:
+            rows = await cfd.get(datasets.TaiwanStockPrice, stock_id="2330")
+            results = await asyncio.gather(*[cfd.get(..., stock_id=s) for s in stocks])
+    """
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 30.0, max_retries: int = 4, backoff_base: float = 0.5,
+                 warn_rate_limit_pct: float = 80.0) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.backoff_base = backoff_base
+        self.warn_rate_limit_pct = warn_rate_limit_pct
+        self.rate_limit_limit: int | None = None
+        self.rate_limit_remaining: int | None = None
+        self.tier: str | None = None
+        hdrs = {"Authorization": f"Bearer {api_key}", "User-Agent": f"clarifindata-py/{__version__}"}
+        try:
+            self._http = httpx.AsyncClient(base_url=self.base_url, timeout=timeout, http2=True, headers=hdrs)
+        except Exception:
+            self._http = httpx.AsyncClient(base_url=self.base_url, timeout=timeout, headers=hdrs)
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    def __repr__(self) -> str:
+        return f"AsyncClient(base_url={self.base_url!r}, key={_mask(self.api_key)}, tier={self.tier})"
+
+    def _track(self, r: httpx.Response) -> None:
+        Client._track_rate_limit(self, r)  # reuse the same logic
+
+    async def _request(self, method: str, path: str, *, params=None, json_body=None, dataset=None) -> dict:
+        import asyncio
+        params = params or {}
+        last: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                r = await self._http.request(method, path, params=params, json=json_body)
+                self._track(r)
+                if r.status_code in _RETRY_STATUS and attempt < self.max_retries:
+                    ra = r.headers.get("retry-after")
+                    await asyncio.sleep(_backoff(attempt, self.backoff_base, float(ra) if ra else None))
+                    continue
+                if r.status_code >= 400:
+                    raise _err_from_response(r, dataset)
+                return r.json()
+            except (httpx.TimeoutException, httpx.TransportError) as e:
+                last = e
+                if attempt < self.max_retries:
+                    await asyncio.sleep(_backoff(attempt, self.backoff_base, None))
+                    continue
+                raise ClarifindataError("network error after retries", dataset=dataset) from e
+        raise ClarifindataError("request failed", dataset=dataset) from last
+
+    async def catalog(self) -> list[dict[str, Any]]:
+        return (await self._request("GET", "/v1/data")).get("datasets", [])
+
+    async def get(self, dataset: str, *, stock_id=None, start=None, end=None,
+                  limit: int = 1000, as_df: bool = False):
+        _validate_dataset(dataset)
+        if limit > ROW_CAP:
+            raise ValidationError(f"limit {limit} exceeds {ROW_CAP}", dataset=dataset)
+        body = await self._request("GET", f"/v1/data/{dataset}",
+                                   params=_params(stock_id, start, end, limit), dataset=dataset)
+        rows = body.get("data", [])
+        if len(rows) == limit and body.get("next_cursor") is None:
+            log.warning("'%s' returned exactly limit=%d — likely truncated.", dataset, limit)
+        return _to_df(rows) if as_df else rows
+
+    async def _pull_window(self, dataset: str, *, stock_id=None, start=None, end=None) -> list:
+        """Async mirror of Client._pull_window — drains one window by following
+        `next_cursor` until null."""
+        out: list[dict[str, Any]] = []
+        cursor: str | None = None
+        while True:
+            body = await self._request("GET", f"/v1/data/{dataset}",
+                                       params=_params(stock_id, start, end, ROW_CAP, cursor),
+                                       dataset=dataset)
+            out.extend(body.get("data", []))
+            cursor = body.get("next_cursor")
+            if not cursor:
+                return out
+
+    async def iter_history(self, dataset: str, *, stock_id=None,
+                           since: date | str | None = None, until: date | str | None = None,
+                           as_df: bool = False) -> list:
+        """Async mirror of Client.iter_history. Returns the list of per-chunk
+        batches (each a list[dict] or DataFrame); iterate with a plain `for`.
+
+        When `since` is None, returns a single batch capped at ROW_CAP."""
+        _validate_dataset(dataset)
+        batches: list = []
+        if since is None:
+            rows = await self._pull_window(dataset, stock_id=stock_id)
+            if rows:
+                batches.append(_to_df(rows) if as_df else rows)
+            return batches
+        s = _as_date(since)
+        u = _as_date(until) if until else date.today()
+        for cs, ce in _month_chunks(s, u):
+            rows = await self._pull_window(dataset, stock_id=stock_id, start=cs, end=ce)
+            if rows:
+                batches.append(_to_df(rows) if as_df else rows)
+        return batches
+
+    async def history(self, dataset: str, **kw) -> list[dict[str, Any]]:
+        """Convenience: fully materialise iter_history into one list (or DataFrame).
+
+        `since` is optional: omit it for datasets with no date axis."""
+        as_df = kw.pop("as_df", False)
+        out: list[dict[str, Any]] = []
+        for batch in await self.iter_history(dataset, **kw):
+            out.extend(batch)
+        return _to_df(out) if as_df else out
+
+    async def bulk_pull(self, datasets: list[str], *, start: date | str | None = None,
+                        end: date | str | None = None, stock_id: str | None = None,
+                        as_df: bool = False) -> dict[str, Any]:
+        """Fetch several datasets for the same window concurrently.
+        Returns {dataset: rows|DataFrame}."""
+        import asyncio
+        rows_per = await asyncio.gather(*[
+            self._pull_window(d, stock_id=stock_id, start=start, end=end)
+            for d in datasets
+        ])
+        return {d: (_to_df(rows) if as_df else rows)
+                for d, rows in zip(datasets, rows_per)}
+
+    async def ask(self, question: str, *, as_df: bool = False):
+        body = await self._request("POST", "/v1/ask", json_body={"question": question})
+        return _to_df(body.get("data", [])) if as_df else body

clarifindata/datasets.py

@@ -0,0 +1,148 @@
+"""Dataset name constants + tier map — autogenerated from the live catalog.
+
+Use these instead of raw strings to get IDE autocomplete + catch typos early:
+
+    from clarifindata import datasets
+    cfd.get(datasets.TaiwanStockPrice, stock_id="2330")
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Type
+
+try:  # py3.8+ stdlib; kept here for an explicit, py3.9-safe import
+    from typing import TypedDict
+except ImportError:  # pragma: no cover
+    from typing_extensions import TypedDict  # type: ignore[assignment]
+
+# --- response row typing -------------------------------------------------
+#
+# A single API response row is a plain JSON object (dict). The concrete
+# columns vary per dataset and are defined by the live server catalog, which
+# is NOT shipped with this client, so we cannot hand-author a verified
+# TypedDict per dataset without guessing column names.
+#
+# `DatasetRow` is the generic, always-correct row type — use it to annotate
+# response rows and get a typed alias for `list[DatasetRow]`:
+#
+#     from clarifindata import DatasetRow
+#     rows: list[DatasetRow] = cfd.get(datasets.TaiwanStockPrice, stock_id="2330")
+#
+# Per-dataset TypedDicts (for richer IDE autocomplete on columns) can be
+# code-generated from the catalog; when available they should be registered
+# in `DATASET_ROW_TYPES` below, mapping dataset name -> TypedDict subclass.
+DatasetRow = Dict[str, Any]
+
+
+class Row(TypedDict, total=False):
+    """Generic typed view of a response row.
+
+    Open shape (``total=False``) — every key is optional because columns
+    differ per dataset. Subclass this for code-generated per-dataset row
+    types and register them in :data:`DATASET_ROW_TYPES`.
+    """
+
+
+# dataset name -> per-dataset TypedDict row type (populate from catalog).
+# Empty until verified per-dataset shapes are generated; consumers should
+# fall back to ``DatasetRow`` for any dataset not present here.
+DATASET_ROW_TYPES: Dict[str, Type[Row]] = {}
+
+# name -> minimum tier required ("free" | "lite" | "plus")
+DATASET_TIERS: dict[str, str] = {
+    'CentralBankRate': 'free',
+    'CrudeOilPrices': 'free',
+    'CryptoFearAndGreedIndex': 'plus',
+    'CurrencyCirculation': 'free',
+    'ExchangeRate': 'free',
+    'FearAndGreedIndex': 'plus',
+    'GoldPrice': 'free',
+    'TaiwanCBDaily': 'free',
+    'TaiwanCBDailyOverview': 'free',
+    'TaiwanCBInstitutionalInvestors': 'free',
+    'TaiwanCBOverview': 'plus',
+    'TaiwanDailyShortSaleBalances': 'free',
+    'TaiwanFinancialHoldingsCompany': 'lite',
+    'TaiwanFutOptInstitutionalInvestors': 'free',
+    'TaiwanFutureOptionDailyTotalOverview': 'free',
+    'TaiwanFutureOptionTickRealtime': 'free',
+    'TaiwanFuturesBrokerDaily': 'lite',
+    'TaiwanFuturesBrokerInfo': 'free',
+    'TaiwanFuturesDaily': 'free',
+    'TaiwanFuturesInstitutionalInvestors': 'free',
+    'TaiwanFuturesLargeTraders': 'lite',
+    'TaiwanFuturesNightInstitutionalInvestors': 'lite',
+    'TaiwanFuturesSettlement': 'lite',
+    'TaiwanFuturesSpread': 'lite',
+    'TaiwanFuturesTradeTick': 'free',
+    'TaiwanIndex5Seconds': 'plus',
+    'TaiwanIndexRealtime': 'plus',
+    'TaiwanMonthlyEconomicIndicator': 'lite',
+    'TaiwanOptionDaily': 'free',
+    'TaiwanOptionInstitutionalInvestors': 'free',
+    'TaiwanOptionsBrokerDaily': 'lite',
+    'TaiwanOptionsFSP': 'free',
+    'TaiwanOptionsLargeTraders': 'lite',
+    'TaiwanOptionsNightInstitutionalInvestors': 'lite',
+    'TaiwanOptionsSettlement': 'lite',
+    'TaiwanOptionsTradeTick': 'free',
+    'TaiwanRelatedNews': 'free',
+    'TaiwanReturnIndex': 'free',
+    'TaiwanStock10Year': 'lite',
+    'TaiwanStock5SecondsOrderStats': 'plus',
+    'TaiwanStockAnalystEstimate': 'plus',
+    'TaiwanStockBalanceSheet': 'free',
+    'TaiwanStockBlockTrade': 'free',
+    'TaiwanStockBorrowingCollateral': 'free',
+    'TaiwanStockBrokerInfo': 'free',
+    'TaiwanStockCapitalReductionReferencePrice': 'free',
+    'TaiwanStockCashFlowsStatement': 'free',
+    'TaiwanStockChangeFaceReference': 'free',
+    'TaiwanStockCompanyIndustry': 'lite',
+    'TaiwanStockCreditLimit': 'free',
+    'TaiwanStockDailyPriceLimit': 'lite',
+    'TaiwanStockDayTradingFee': 'lite',
+    'TaiwanStockDayTradingInfo': 'free',
+    'TaiwanStockDelisting': 'free',
+    'TaiwanStockDisposition': 'lite',
+    'TaiwanStockDividend': 'free',
+    'TaiwanStockDividendResult': 'free',
+    'TaiwanStockFinancialStatement': 'free',
+    'TaiwanStockHoldingSharesPer': 'lite',
+    'TaiwanStockInstitutionalInvestorsBuySell': 'lite',
+    'TaiwanStockKBar1Min': 'plus',
+    'TaiwanStockMarginPurchaseShortSale': 'lite',
+    'TaiwanStockMarginRatio': 'lite',
+    'TaiwanStockMarginShortSaleSuspension': 'lite',
+    'TaiwanStockMarketValue': 'lite',
+    'TaiwanStockMarketValueWeight': 'lite',
+    'TaiwanStockMonthPrice': 'lite',
+    'TaiwanStockMonthRevenue': 'lite',
+    'TaiwanStockOverview': 'free',
+    'TaiwanStockOverviewIncludeWarrant': 'free',
+    'TaiwanStockPER': 'free',
+    'TaiwanStockPrice': 'lite',
+    'TaiwanStockPriceAdj': 'lite',
+    'TaiwanStockRealtime': 'plus',
+    'TaiwanStockSectorPrice': 'free',
+    'TaiwanStockSecuritiesLending': 'free',
+    'TaiwanStockShareholding': 'lite',
+    'TaiwanStockSplitPrice': 'free',
+    'TaiwanStockSuspendDayTrading': 'lite',
+    'TaiwanStockTotalInstitutionalInvestors': 'free',
+    'TaiwanStockTotalMarginPurchaseShortSale': 'free',
+    'TaiwanStockTradingDate': 'free',
+    'TaiwanStockTradingHaltAnnouncement': 'lite',
+    'TaiwanStockWarrantInfo': 'free',
+    'TaiwanStockWeekPrice': 'lite',
+    'TaiwanWeightedIndex': 'free',
+    'USBondYield': 'free',
+    'USStockKBars': 'plus',
+    'USStockPrice': 'free',
+}
+
+ALL: frozenset[str] = frozenset(DATASET_TIERS)
+
+# expose each dataset name as a module attribute: datasets.TaiwanStockPrice
+for _n in DATASET_TIERS:
+    globals()[_n] = _n
+del _n

clarifindata/errors.py

@@ -0,0 +1,48 @@
+"""Typed exceptions with actionable suggestions (instead of raw httpx errors)."""
+from __future__ import annotations
+
+
+class ClarifindataError(Exception):
+    """Base error. Carries the dataset, HTTP status, server detail and a hint."""
+
+    def __init__(self, message: str, *, dataset: str | None = None,
+                 status: int | None = None, detail: str | None = None,
+                 suggestion: str | None = None) -> None:
+        self.dataset = dataset
+        self.status = status
+        self.detail = detail
+        self.suggestion = suggestion
+        parts = [message]
+        if dataset:
+            parts.append(f"dataset={dataset}")
+        if status:
+            parts.append(f"HTTP {status}")
+        if detail:
+            parts.append(f"detail={detail}")
+        if suggestion:
+            parts.append(f"\n  → {suggestion}")
+        super().__init__(" ".join(parts))
+
+
+class AuthError(ClarifindataError):
+    """401/403 — bad/missing key, or the dataset needs a higher tier."""
+
+
+class TierError(AuthError):
+    """403 — your tier can't access this dataset/endpoint."""
+
+
+class RateLimitError(ClarifindataError):
+    """429 — rate limit hit (after retries were exhausted)."""
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kw) -> None:
+        self.retry_after = retry_after
+        super().__init__(message, **kw)
+
+
+class NotFoundError(ClarifindataError):
+    """404 — unknown dataset/endpoint."""
+
+
+class ValidationError(ClarifindataError):
+    """400/422 — bad parameters (e.g. dataset typo, limit > 10000)."""

clarifindata-0.2.5.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: clarifindata
+Version: 0.2.5
+Summary: Python client for the 金晰數據 / clarifindata Taiwan-stock data API
+Project-URL: Homepage, https://clarifindata.com
+Project-URL: Documentation, https://clarifindata.com/docs
+Project-URL: Source, https://github.com/AChao0212/clarifindata-python
+Author: clarifindata
+License: MIT
+License-File: LICENSE
+Keywords: data,finance,quant,stock,taiwan,tpex,twse
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: all
+Requires-Dist: h2>=4.0; extra == 'all'
+Requires-Dist: pandas>=1.5; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: http2
+Requires-Dist: h2>=4.0; extra == 'http2'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# clarifindata — Python client
+
+Python client for the **金晰數據 / clarifindata** Taiwan-stock data API (89 datasets:
+prices, chips, fundamentals, derivatives, macro — full history, refreshed daily).
+
+```bash
+pip install clarifindata            # core
+pip install 'clarifindata[pandas]'  # + DataFrame output (as_df=True)
+pip install 'clarifindata[all]'     # + pandas + HTTP/2
+```
+
+## Quickstart
+
+```python
+from clarifindata import Client, datasets
+
+cfd = Client(api_key="cfd_demo_free_0001")          # free demo key
+
+# typed dataset names (autocomplete + typo-safe), DataFrame output
+df = cfd.get(datasets.TaiwanStockPrice, stock_id="2330",
+             start="2026-04-01", end="2026-06-03", as_df=True)
+print(df.head())
+```
+
+**Demo keys** (rate-limited, for trying out): `cfd_demo_free_0001` (Free),
+`cfd_demo_lite_0001` (Lite). Get your own at <https://clarifindata.com/signup>.
+
+## Features
+
+| What | How |
+|------|-----|
+| **Auto-retry** 429/5xx/timeouts (honours `Retry-After`, exp backoff) | on by default; tune `max_retries`, `backoff_base` |
+| **Rate-limit aware** | `cfd.rate_limit_remaining`; warns at 80% used |
+| **DataFrame output** | `cfd.get(..., as_df=True)` |
+| **Full-history streaming** (auto-paginates the 10 000-row cap) | `cfd.iter_history(ds, stock_id=..., since="2015-01-01")` |
+| **Async / concurrency** | `AsyncClient` (same surface) |
+| **Multi-dataset pull** | `cfd.bulk_pull([...], start=, end=)` |
+| **Disk cache** (for slow-changing datasets) | `Client(cache_dir="./.cache", cache_ttl=86400)` |
+| **Typed errors w/ suggestions** | `ClarifindataError(dataset, status, detail, suggestion)` |
+| **Logging** | `logging.getLogger("clarifindata")` (DEBUG = request/response) |
+
+## Full history (any range, no manual chunking)
+
+```python
+for batch in cfd.iter_history(datasets.TaiwanStockPrice, stock_id="2330", since="2015-01-01"):
+    process(batch)                                  # one year per batch, streamed
+
+df = cfd.history(datasets.TaiwanStockPrice, stock_id="2330", since="2015-01-01", as_df=True)
+```
+
+## Concurrency (fetch many stocks)
+
+```python
+import asyncio
+from clarifindata import AsyncClient, datasets
+
+async def main():
+    async with AsyncClient(api_key="...") as cfd:
+        tasks = [cfd.get(datasets.TaiwanStockPrice, stock_id=s, as_df=True)
+                 for s in ("2330", "2317", "2454")]
+        return await asyncio.gather(*tasks)
+
+frames = asyncio.run(main())
+```
+
+## Natural-language queries (Plus tier)
+
+```python
+ans = cfd.ask("找出 2330 在 2026 年 4 月最高收盤價那天", as_df=True)
+```
+
+## Errors
+
+```python
+from clarifindata import TierError, RateLimitError, ValidationError
+try:
+    cfd.get("TaiwanStockPirce")          # typo
+except ValidationError as e:
+    print(e)        # Unknown dataset 'TaiwanStockPirce'. Did you mean 'TaiwanStockPrice'? ...
+```

clarifindata-0.2.5.dist-info/RECORD

@@ -0,0 +1,8 @@
+clarifindata/__init__.py,sha256=qk3A7-ohMU8gCUsNqmGTmQCdJN_tmLcbpb1drdncSmo,1122
+clarifindata/client.py,sha256=Ie3aZbxlLvX0LqlNjH3Y-uytFUlkXKnXzXcG2xGkMmU,22546
+clarifindata/datasets.py,sha256=rb2nCgDdpkstYwMOieUsMjKgXYSSSQelHMqHVR77BqQ,5802
+clarifindata/errors.py,sha256=07qhYhXnY7uU4bq78VnKWE4j5typG4SIq7oIOdB4weQ,1581
+clarifindata-0.2.5.dist-info/METADATA,sha256=4JXr4ehRVjAt6pXeJQjx0WLtetgRzQJo7mrNJwyPMd0,3691
+clarifindata-0.2.5.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+clarifindata-0.2.5.dist-info/licenses/LICENSE,sha256=hvrW2KkWGXpSwgcZeVLzDNS3JnLvO6RJ4gtmZ60uNmk,1069
+clarifindata-0.2.5.dist-info/RECORD,,

clarifindata-0.2.5.dist-info/WHEEL

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

clarifindata-0.2.5.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 clarifindata
+
+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.