vquanty 0.1.0__tar.gz

vquanty-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[oc]
+.venv/
+dist/
+build/
+*.egg-info
+.env
+.pytest_cache/
+.ruff_cache/
+.DS_Store

vquanty-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.5
+Name: vquanty
+Version: 0.1.0
+Summary: Client for the personal TEJ data API (FinLab-style wide frames with local cache)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# vquanty
+
+Client for a personal Taiwan market data API. Returns FinLab-style wide
+frames (index = date, columns = security code) and caches them locally;
+a frame is downloaded again only when the server data changes.
+
+Access requires an API key issued by the server owner.
+
+```bash
+pip install vquanty
+```
+
+```python
+import vquanty
+
+vquanty.login("tej_...")  # or set VQUANTY_API_KEY
+from vquanty import data
+
+close = data.get("price:收盤價")
+```
+
+Environment variables: `VQUANTY_API_KEY`, `VQUANTY_BASE_URL`,
+`VQUANTY_CACHE_DIR`, `VQUANTY_CF_CLIENT_ID`, `VQUANTY_CF_CLIENT_SECRET`.

vquanty-0.1.0/README.md

@@ -0,0 +1,23 @@
+# vquanty
+
+Client for a personal Taiwan market data API. Returns FinLab-style wide
+frames (index = date, columns = security code) and caches them locally;
+a frame is downloaded again only when the server data changes.
+
+Access requires an API key issued by the server owner.
+
+```bash
+pip install vquanty
+```
+
+```python
+import vquanty
+
+vquanty.login("tej_...")  # or set VQUANTY_API_KEY
+from vquanty import data
+
+close = data.get("price:收盤價")
+```
+
+Environment variables: `VQUANTY_API_KEY`, `VQUANTY_BASE_URL`,
+`VQUANTY_CACHE_DIR`, `VQUANTY_CF_CLIENT_ID`, `VQUANTY_CF_CLIENT_SECRET`.

vquanty-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "vquanty"
+version = "0.1.0"
+description = "Client for the personal TEJ data API (FinLab-style wide frames with local cache)"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pandas>=2.0",
+    "pyarrow>=14",
+    "requests>=2.31",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vquanty"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["vquanty", "README.md", "pyproject.toml"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "python-dotenv>=1",
+    "ruff>=0.6",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vquanty-0.1.0/vquanty/__init__.py

@@ -0,0 +1,41 @@
+"""Client for the personal TEJ data API.
+
+import vquanty
+vquanty.login("tej_...")  # saved for next time
+from vquanty import data
+close = data.get("price:收盤價")
+"""
+
+from __future__ import annotations
+
+from . import _state, data
+from ._client import CONFIG_PATH, AuthError, Client, Config, VquantyError
+
+__all__ = ["AuthError", "Client", "Config", "VquantyError", "data", "login", "logout"]
+
+
+def login(
+    api_key: str,
+    base_url: str | None = None,
+    cf_client_id: str | None = None,
+    cf_client_secret: str | None = None,
+    save: bool = True,
+) -> None:
+    """Set credentials; with ``save`` they persist in ~/.config/vquanty/config.json (0600)."""
+    config = Config.load()
+    config.api_key = api_key
+    config.base_url = base_url or config.base_url
+    config.cf_client_id = cf_client_id or config.cf_client_id
+    config.cf_client_secret = cf_client_secret or config.cf_client_secret
+    if not config.base_url:
+        raise ValueError("base_url is required on first login")
+    client = Client(config)
+    client.get_json("/v1/datasets")  # fail fast on a bad key or URL
+    if save:
+        config.save()
+    _state.reset(client)
+
+
+def logout() -> None:
+    CONFIG_PATH.unlink(missing_ok=True)
+    _state.reset()

vquanty-0.1.0/vquanty/_client.py

@@ -0,0 +1,218 @@
+"""HTTP client with an ETag-validated local Parquet cache.
+
+Each key is cached on disk as ``<sha1(key)>.parquet`` plus a JSON sidecar
+holding the server's ETag (the data fingerprint). A fetch sends the ETag back
+as ``If-None-Match``; the server answers 304 when nothing changed, so a frame
+is downloaded once per data update per device. Within one process a frame is
+not revalidated again for ``revalidate_after`` seconds.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+import warnings
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import pandas as pd
+import requests
+
+CONFIG_PATH = Path(
+    os.environ.get("VQUANTY_CONFIG") or Path.home() / ".config/vquanty/config.json"
+)
+DEFAULT_BASE_URL = "https://vquanty.ai-quantamental.com"
+DEFAULT_CACHE = Path(
+    os.environ.get("VQUANTY_CACHE_DIR") or Path.home() / ".cache/vquanty"
+)
+
+
+class VquantyError(RuntimeError):
+    pass
+
+
+class AuthError(VquantyError):
+    pass
+
+
+@dataclass
+class Config:
+    api_key: str | None = None
+    base_url: str | None = None
+    cf_client_id: str | None = None
+    cf_client_secret: str | None = None
+    cache_dir: Path = DEFAULT_CACHE
+    revalidate_after: float = 300.0
+
+    @classmethod
+    def load(cls) -> Config:
+        saved: dict = {}
+        if CONFIG_PATH.exists():
+            saved = json.loads(CONFIG_PATH.read_text())
+        env = os.environ.get
+        return cls(
+            api_key=env("VQUANTY_API_KEY") or saved.get("api_key"),
+            base_url=env("VQUANTY_BASE_URL")
+            or saved.get("base_url")
+            or DEFAULT_BASE_URL,
+            cf_client_id=env("VQUANTY_CF_CLIENT_ID") or saved.get("cf_client_id"),
+            cf_client_secret=env("VQUANTY_CF_CLIENT_SECRET")
+            or saved.get("cf_client_secret"),
+        )
+
+    def save(self) -> None:
+        CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            k: v
+            for k, v in {
+                "api_key": self.api_key,
+                "base_url": None
+                if self.base_url == DEFAULT_BASE_URL
+                else self.base_url,
+                "cf_client_id": self.cf_client_id,
+                "cf_client_secret": self.cf_client_secret,
+            }.items()
+            if v
+        }
+        tmp = CONFIG_PATH.with_suffix(".tmp")
+        tmp.write_text(json.dumps(payload, indent=2))
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, CONFIG_PATH)
+
+
+@dataclass
+class Client:
+    config: Config = field(default_factory=Config.load)
+    _memo: dict[str, tuple[str, pd.DataFrame, float]] = field(
+        default_factory=dict, repr=False
+    )
+    _session: requests.Session = field(default_factory=requests.Session, repr=False)
+
+    # -- http -------------------------------------------------------------------
+    def _headers(self) -> dict[str, str]:
+        cfg = self.config
+        if not cfg.api_key or not cfg.base_url:
+            raise AuthError("not logged in; call vquanty.login(api_key)")
+        headers = {"Authorization": f"Bearer {cfg.api_key}"}
+        if cfg.cf_client_id and cfg.cf_client_secret:
+            headers["CF-Access-Client-Id"] = cfg.cf_client_id
+            headers["CF-Access-Client-Secret"] = cfg.cf_client_secret
+        return headers
+
+    def _url(self, path: str) -> str:
+        return self.config.base_url.rstrip("/") + path
+
+    @staticmethod
+    def _raise_for(resp: requests.Response) -> None:
+        if resp.status_code < 400:
+            return
+        try:
+            detail = resp.json().get("detail", resp.text)
+        except ValueError:
+            detail = resp.text[:300]
+        if resp.status_code == 401:
+            raise AuthError(f"API key rejected: {detail}")
+        if resp.status_code == 403:
+            raise AuthError(
+                "blocked before reaching the server (Cloudflare Access?); check cf_client_id/secret"
+            )
+        if resp.status_code == 404:
+            raise KeyError(detail)
+        raise VquantyError(f"HTTP {resp.status_code}: {detail}")
+
+    def get_json(self, path: str):
+        resp = self._session.get(
+            self._url(path), headers=self._headers(), timeout=(10, 60)
+        )
+        self._raise_for(resp)
+        return resp.json()
+
+    # -- cache ------------------------------------------------------------------
+    def _paths(self, key: str) -> tuple[Path, Path]:
+        stem = hashlib.sha1(key.encode()).hexdigest()
+        base = Path(self.config.cache_dir)
+        return base / f"{stem}.parquet", base / f"{stem}.json"
+
+    def _read_cached(self, key: str) -> tuple[str, pd.DataFrame] | None:
+        data_path, meta_path = self._paths(key)
+        if not (data_path.exists() and meta_path.exists()):
+            return None
+        meta = json.loads(meta_path.read_text())
+        return meta["etag"], pd.read_parquet(data_path)
+
+    def get(self, key: str, force_download: bool = False) -> pd.DataFrame:
+        now = time.monotonic()
+        memo = self._memo.get(key)
+        if memo and not force_download and now - memo[2] < self.config.revalidate_after:
+            return memo[1].copy()
+
+        cached = (
+            None
+            if force_download
+            else ((memo[0], memo[1]) if memo else self._read_cached(key))
+        )
+        headers = self._headers()
+        if cached:
+            headers["If-None-Match"] = cached[0]
+        try:
+            resp = self._session.get(
+                self._url("/v1/data"),
+                params={"key": key},
+                headers=headers,
+                timeout=(10, 600),
+                stream=True,
+            )
+        except requests.RequestException as exc:
+            if cached:
+                warnings.warn(
+                    f"server unreachable ({exc.__class__.__name__}); using cached {key}",
+                    stacklevel=2,
+                )
+                self._memo[key] = (cached[0], cached[1], now)
+                return cached[1].copy()
+            raise VquantyError(
+                f"server unreachable and {key!r} not cached: {exc}"
+            ) from exc
+
+        if resp.status_code == 304 and cached:
+            resp.close()
+            self._memo[key] = (cached[0], cached[1], now)
+            return cached[1].copy()
+        if resp.status_code == 503 and cached:
+            resp.close()
+            warnings.warn(
+                f"server busy updating data; using cached {key}", stacklevel=2
+            )
+            return cached[1].copy()
+        self._raise_for(resp)
+
+        data_path, meta_path = self._paths(key)
+        data_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = data_path.with_suffix(f".{os.getpid()}.tmp")
+        with tmp.open("wb") as out:
+            for chunk in resp.iter_content(chunk_size=1 << 20):
+                out.write(chunk)
+        os.replace(tmp, data_path)
+        etag = resp.headers.get("ETag", "")
+        meta_path.write_text(
+            json.dumps(
+                {
+                    "key": key,
+                    "etag": etag,
+                    "server_key": resp.headers.get("X-Tej-Key"),
+                    "fetched_at": time.time(),
+                },
+                ensure_ascii=False,
+            )
+        )
+        df = pd.read_parquet(data_path)
+        self._memo[key] = (etag, df, now)
+        return df.copy()
+
+    def clear_cache(self) -> None:
+        self._memo.clear()
+        base = Path(self.config.cache_dir)
+        for path in list(base.glob("*.parquet")) + list(base.glob("*.json")):
+            path.unlink(missing_ok=True)

vquanty-0.1.0/vquanty/_state.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from ._client import Client
+
+_client: Client | None = None
+
+
+def client() -> Client:
+    global _client
+    if _client is None:
+        _client = Client()
+    return _client
+
+
+def reset(new: Client | None = None) -> None:
+    global _client
+    _client = new

vquanty-0.1.0/vquanty/data.py

@@ -0,0 +1,33 @@
+"""FinLab-style data access.
+
+from vquanty import data
+close = data.get("price:收盤價")       # DataFrame, index=date, columns=coid
+data.datasets()                         # what can be pivoted
+data.fields("price")                    # field keys of one dataset
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from . import _state
+
+
+def get(key: str, force_download: bool = False) -> pd.DataFrame:
+    """Wide frame for ``dataset:field``; downloads only when the server data changed."""
+    return _state.client().get(key, force_download=force_download)
+
+
+def datasets() -> pd.DataFrame:
+    return pd.DataFrame(_state.client().get_json("/v1/datasets"))
+
+
+def fields(dataset: str) -> pd.DataFrame:
+    from urllib.parse import quote
+
+    info = _state.client().get_json(f"/v1/datasets/{quote(dataset, safe='')}")
+    return pd.DataFrame(info["fields"])
+
+
+def clear_cache() -> None:
+    _state.client().clear_cache()